The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
// GENERATED by scripts/gen_gateway_contracts.py from tui_gateway/contracts — DO NOT EDIT.
// Regenerate: .venv/bin/python scripts/gen_gateway_contracts.py
// tests/tui_gateway/contracts/test_generated.py fails when this file is stale.
/* eslint-disable */
// ── Types ──
/** Any method the desktop may route to a named profile (``requestGatewayForProfile`` adds ``profile``). */
export interface ProfileParams {
profile?: string | null
}
/** ``_serialize_usage_model`` — also embedded as ``usage`` in the billing / subscription states, where the fail-open form is a bare ``{available: false}`` (no ``ok``). */
export interface UsageModel {
ok?: boolean | null
available: boolean
status?: string | null
plan_name?: string | null
renews_at?: string | null
renews_display?: string | null
subscription_remaining_display?: string | null
topup_remaining_display?: string | null
total_spendable_display?: string | null
has_topup?: boolean | null
plan_bar?: UsageBar | null
topup_bar?: UsageBar | null
}
/** ``_serialize_usage_bar``: one bar, magnitudes pre-formatted; ``pct_used`` only for ``plan``. */
export interface UsageBar {
kind: UsageBarKind
remaining_display: string
total_display: string
spent_display: string
pct_used?: number | null
fill_fraction: number
}
export type UsageBarKind = 'plan' | 'topup'
/** ``_serialize_billing_state`` (money as strings); the ``except`` fallback emits only ``ok / logged_in / free_tier_account / error``, so everything else is optional. */
export interface BillingStateResult {
ok: boolean
logged_in: boolean
free_tier_account?: boolean
free_tier_model?: string | null
org_name?: string | null
org_slug?: string | null
role?: string | null
is_admin?: boolean | null
can_change_plan?: boolean | null
can_charge?: boolean | null
balance_usd?: string | null
balance_display?: string | null
cli_billing_enabled?: boolean | null
charge_presets?: string[] | null
charge_presets_display?: string[] | null
min_usd?: string | null
max_usd?: string | null
card?: BillingCardInfo | null
payment_method?: BillingPaymentMethod | null
monthly_cap?: BillingMonthlyCap | null
auto_reload?: BillingAutoReload | null
keep_going_on_credits?: boolean | null
portal_url?: string | null
error?: string | null
usage?: UsageModel | null
plan_usage?: PlanUsage | null
}
export interface BillingCardInfo {
brand: string
last4: string
masked: string
display?: string | null
resolved_via?: string | null
}
/** ``_serialize_payment_method``: each kind emits only its own fields (a ``card`` never carries ``email``; ``unknown`` carries what the server called it in ``raw_kind``). */
export interface BillingPaymentMethod {
kind: PaymentMethodKind
brand?: string | null
last4?: string | null
wallet?: string | null
email?: string | null
raw_kind?: string | null
resolved_via?: string | null
}
export type PaymentMethodKind = 'card' | 'link' | 'unknown'
export interface BillingMonthlyCap {
limit_usd?: string | null
limit_display: string
spent_this_month_usd?: string | null
spent_display: string
is_default_ceiling: boolean
}
export interface BillingAutoReload {
enabled: boolean
threshold_usd?: string | null
threshold_display: string
reload_to_usd?: string | null
reload_to_display: string
card?: BillingAutoReloadCard | null
}
/** Only ``distinct`` carries the payment-method identity. */
export interface BillingAutoReloadCard {
kind: AutoReloadCardKind
payment_method_id?: string | null
brand?: string | null
last4?: string | null
}
export type AutoReloadCardKind = 'canonical' | 'distinct' | 'none'
/** ``hermes_cli/model_picker_usage.py::PickerUsage.to_payload`` — usage-window plan chrome. */
export interface PlanUsage {
kind: string
plan?: string | null
gauges?: PlanUsageGauge[]
top_tier_model_ids?: string[]
subscription_model_ids?: string[]
featured_model_ids?: string[]
paused_reason?: string | null
credits_pay?: boolean | null
}
/** One server allowance on ``ModelOptionProvider.plan_usage``, in the server's order. ``label`` is the server's id (``day`` / ``week`` / ``month`` / ``top_tier`` have client words; any other id shows ``title``). ``scope``: which models a full one stops (``all`` / ``top_tier``). */
export interface PlanUsageGauge {
label: string
left_fraction: number
style: string
resets_at_ms?: number | null
scope?: string
title?: string
}
/** ``_serialize_subscription_state``; the view's fallback emits only ``ok / logged_in / error``. */
export interface SubscriptionStateResult {
ok: boolean
logged_in: boolean
is_admin?: boolean | null
can_change_plan?: boolean | null
org_name?: string | null
org_id?: string | null
role?: string | null
context?: SubscriptionContext | null
current?: CurrentSubscription | null
tiers?: SubscriptionTierOption[] | null
portal_url?: string | null
error?: string | null
usage?: UsageModel | null
plan_usage?: PlanUsage | null
}
export type SubscriptionContext = 'personal' | 'team'
export interface CurrentSubscription {
tier_id?: string | null
tier_name?: string | null
monthly_credits?: string | null
credits_remaining?: string | null
cycle_ends_at?: string | null
pending_downgrade_tier_name?: string | null
pending_downgrade_at?: string | null
pending_downgrade_display?: string | null
cancel_at_period_end: boolean
cancellation_effective_at?: string | null
cancellation_effective_display?: string | null
}
export interface SubscriptionTierOption {
tier_id: string
name: string
tier_order: number
dollars_per_month_display: string
monthly_credits?: string | null
is_current: boolean
is_enabled: boolean
}
export interface SubscriptionPreviewParams {
profile?: string | null
subscription_type_id?: string | null
}
/** ``_serialize_subscription_preview`` on success; ``effect`` drives the confirm copy. */
export interface SubscriptionPreviewResult {
ok: boolean
error?: string | null
message?: string | null
portal_url?: string | null
retry_after?: number | null
payload?: Record<string, unknown> | null
actor?: string | null
code?: string | null
recovery?: string | null
effect?: SubscriptionChangeEffect | null
reason?: string | null
current_tier_id?: string | null
current_tier_name?: string | null
target_tier_id?: string | null
target_tier_name?: string | null
monthly_credits_delta?: string | null
amount_due_now_cents?: number | null
effective_at?: string | null
}
export type SubscriptionChangeEffect = 'charge_now' | 'scheduled' | 'no_op' | 'blocked'
/** Either a target tier (downgrade / same-price change) or ``cancel`` (period-end cancellation). */
export interface SubscriptionChangeParams {
profile?: string | null
subscription_type_id?: string | null
cancel?: boolean
}
/** ``_billing_pending_change``: ``message`` + the raw NAS body in ``payload`` on success. */
export interface BillingPendingChangeResult {
ok: boolean
error?: string | null
message?: string | null
portal_url?: string | null
retry_after?: number | null
payload?: Record<string, unknown> | null
actor?: string | null
code?: string | null
recovery?: string | null
}
export interface SubscriptionUpgradeParams {
profile?: string | null
subscription_type_id?: string | null
idempotency_key?: string | null
}
/** The money route: ``status`` separates a completed upgrade from an SCA / decline that must finish in the portal at ``recovery_url``; ``idempotency_key`` is echoed (also on error) so a retry reuses it. */
export interface SubscriptionUpgradeResult {
ok: boolean
error?: string | null
message?: string | null
portal_url?: string | null
retry_after?: number | null
payload?: Record<string, unknown> | null
actor?: string | null
code?: string | null
recovery?: string | null
status?: string | null
target_tier_name?: string | null
recovery_url?: string | null
reason?: string | null
idempotency_key?: string | null
}
export interface BillingChargeParams {
profile?: string | null
amount_usd?: number | string | null
idempotency_key?: string | null
}
/** ``202 {chargeId}`` — money is not confirmed yet; poll ``billing.charge_status``. */
export interface BillingChargeResult {
ok: boolean
error?: string | null
message?: string | null
portal_url?: string | null
retry_after?: number | null
payload?: Record<string, unknown> | null
actor?: string | null
code?: string | null
recovery?: string | null
charge_id?: string | null
idempotency_key?: string | null
}
export interface BillingChargeStatusParams {
profile?: string | null
charge_id?: string | null
}
/** Single status read (pending | settled | failed); the caller drives the poll cadence. */
export interface BillingChargeStatusResult {
ok: boolean
error?: string | null
message?: string | null
portal_url?: string | null
retry_after?: number | null
payload?: Record<string, unknown> | null
actor?: string | null
code?: string | null
recovery?: string | null
status?: string | null
amount_usd?: string | number | null
settled_at?: string | null
reason?: string | null
}
export interface BillingAutoReloadParams {
profile?: string | null
enabled?: boolean
threshold?: number | string | null
top_up_amount?: number | string | null
}
/** A write with no success payload beyond ``ok``. */
export interface BillingMutationResult {
ok: boolean
error?: string | null
message?: string | null
portal_url?: string | null
retry_after?: number | null
payload?: Record<string, unknown> | null
actor?: string | null
code?: string | null
recovery?: string | null
}
export interface BillingKeepGoingOnCreditsParams {
profile?: string | null
enabled?: boolean
}
export interface BillingStepUpParams {
profile?: string | null
session_id?: string | null
}
/** ``granted`` false when the server downscopes (also on every error envelope). */
export interface BillingStepUpResult {
ok: boolean
error?: string | null
message?: string | null
portal_url?: string | null
retry_after?: number | null
payload?: Record<string, unknown> | null
actor?: string | null
code?: string | null
recovery?: string | null
granted?: boolean | null
}
export interface DelegationStatusResult {
active: ActiveSubagent[]
paused: boolean
max_spawn_depth: number
max_concurrent_children: number
}
/** One live child from ``tools/delegate_tool_registry.py::list_active_subagents`` (the record is extended by the child runner — ``missed_steer`` etc. — so it stays open). */
export interface ActiveSubagent {
subagent_id: string
parent_id?: string | null
depth?: number | null
goal?: string | null
delegation_id?: string | null
model?: string | null
started_at?: number | null
status?: string | null
tool_count?: number | null
owner_agent_session_id?: string | null
[key: string]: unknown
}
export interface DelegationPauseParams {
profile?: string | null
paused?: boolean
}
export interface DelegationPauseResult {
paused: boolean
}
export interface SubagentSteerParams {
session_id: string
profile?: string | null
subagent_id: string
text: string
}
/** ``queued`` is not ``delivered``: a child past its final tool batch surfaces ``missed_steer``. */
export interface SubagentSteerResult {
status: SteerStatus
subagent_id: string
text: string
}
export type SteerStatus = 'queued' | 'rejected'
export interface HandoffRequestParams {
session_id: string
profile?: string | null
platform: string
}
export interface HandoffRequestResult {
queued: boolean
session_key: string
platform: string
home_name: string
}
/** Any method addressed at one live session. */
export interface SessionParams {
session_id: string
profile?: string | null
}
/** ``state`` is pending | running | completed | failed, or '' when nothing was requested. */
export interface HandoffStateResult {
state: string
platform: string
error: string
}
export interface HandoffFailParams {
session_id: string
profile?: string | null
error?: string | null
}
/** ``failed`` false when the watcher already claimed the row; ``state`` is what it is now. */
export interface HandoffFailResult {
failed: boolean
state: string
}
/** ``row_id`` is ``messages.id``; a not-yet-persisted live message names ``newest_role`` instead. ``emoji`` null clears; the same emoji again retracts. */
export interface MessageReactParams {
session_id: string
profile?: string | null
row_id?: number | null
newest_role?: string | null
emoji?: string | null
author?: ReactionAuthor | null
}
export type ReactionAuthor = 'user' | 'agent'
export interface MessageReactResult {
row_id: number
reactions: MessageReaction[]
}
/** One persisted reaction row (``hermes_state_messages.set_message_reaction``); ``seen`` is stamped once announced. */
export interface MessageReaction {
emoji: string
author: string
at?: number | null
seen?: boolean | null
[key: string]: unknown
}
export interface PetCancelParams {
profile?: string | null
token?: string | null
}
export interface PetCancelResult {
ok: boolean
}
export interface PetGenerateStatusResult {
available: boolean
providers: PetGenProvider[]
}
/** ``agent/pet/generate/imagegen.py::list_sprite_providers`` row. */
export interface PetGenProvider {
name: string
label: string
default: boolean
}
/** ``prompt`` or a ``referenceImage`` data URL is required (the handler answers 4004 without one). */
export interface PetGenerateParams {
profile?: string | null
prompt?: string | null
referenceImage?: string | null
count?: number | null
style?: string | null
provider?: string | null
}
export interface PetGenerateResult {
ok: boolean
token: string
drafts: PetDraft[]
}
export interface PetDraft {
index: number
dataUri: string
}
export interface PetHatchParams {
profile?: string | null
token: string
name: string
cancelToken?: string | null
index?: number | null
description?: string | null
prompt?: string | null
style?: string | null
provider?: string | null
}
/** The hatched pet is installed but NOT active (``pet.select`` adopts, ``pet.remove`` discards). */
export interface PetHatchResult {
ok: boolean
slug: string
displayName: string
warnings?: unknown[]
pet: PetSpritePayload
}
export interface PetSpritePayload {
slug?: string | null
displayName?: string | null
mime?: string | null
spritesheetBase64?: string | null
spritesheetRevision?: string | null
frameW?: number | null
frameH?: number | null
framesPerState?: number | null
framesByState?: Record<string, number> | null
framesByRow?: Record<string, number> | null
loopMs?: number | null
scale?: number | null
stateRows?: string[] | null
}
export interface ProjectFactsParams {
profile?: string | null
cwd?: string | null
}
/** ``facts`` null outside a workspace (or when detection failed). */
export interface ProjectFactsResult {
facts?: ProjectFacts | null
}
/** ``agent/coding_context.py::project_facts_for`` — the system prompt's coding-context detection. */
export interface ProjectFacts {
root: string
manifests: string[]
packageManagers: string[]
verifyCommands: string[]
contextFiles: string[]
}
/** ``key`` selects one getter from ``_CONFIG_GETTERS``; ``cwd`` feeds the ``project`` getter, ``session_id`` lets ``reasoning`` / ``fast`` answer with the session's live pin. */
export interface ConfigGetParams {
profile?: string | null
key: string
cwd?: string | null
session_id?: string | null
}
/** Union of every getter's payload: ``value`` for the simple words, ``config`` for ``full``, ``mtime`` / ``mcp_rev`` for the poller, ``model`` / ``provider`` / ``providers`` for ``provider``, ``home`` / ``display`` for ``profile``, ``cwd`` / ``branch`` for ``project``, ``prompt``. */
export interface ConfigGetResult {
value?: string | null
display?: string | null
tool_progress?: string | null
model?: string | null
provider?: string | null
providers?: ConfigProviderRef[] | null
home?: string | null
cwd?: string | null
branch?: string | null
config?: Record<string, unknown> | null
prompt?: string | null
mtime?: number | null
mcp_rev?: string | null
}
/** ``hermes_cli/models.py::list_available_providers`` row. */
export interface ConfigProviderRef {
id: string
label: string
aliases?: string[]
authenticated?: boolean
[key: string]: unknown
}
/** ``key`` picks the setter (``_CONFIG_SETTERS``, ``details_mode.<section>``, display toggles); ``value`` is the raw word/string the setter normalises (falsy non-strings are reported back in the error). ``scope`` applies to ``yolo`` / ``reasoning``; ``confirm_expensive_model`` to ``model``. */
export interface ConfigSetParams {
profile?: string | null
key: string
value?: unknown
session_id?: string | null
scope?: string | null
confirm_expensive_model?: boolean
}
/** ``{key, value}`` plus the setter's extras: model switches add ``warning`` / ``confirm_required`` / ``confirm_message`` / ``scope`` / ``deferred``; ``focus`` adds ``tool_progress``; ``cwd`` adds ``cwd`` / ``branch``; ``personality`` adds ``history_reset`` / ``info``; ``yolo`` reports its ``scope``. ``value`` is a bool only for the display toggles. */
export interface ConfigSetResult {
key: string
value?: string | boolean | null
warning?: string | null
confirm_required?: boolean | null
confirm_message?: string | null
scope?: string | null
deferred?: boolean | null
tool_progress?: string | null
cwd?: string | null
branch?: string | null
history_reset?: boolean | null
info?: SessionLiveInfo | null
}
/** ``tui_gateway/server.py::_session_info`` — the ``session.info`` event and the ``info`` field of ``session.create`` / ``session.resume`` / ``session.activate`` results. */
export interface SessionLiveInfo {
model?: string
provider?: string
reasoning_effort?: string
reasoning_effort_wire?: string
service_tier?: string
fast?: boolean
yolo?: boolean
approval_mode?: string
tools?: Record<string, string[]>
skills?: Record<string, string[]>
cwd?: string
branch?: string | null
project?: ProjectRef | null
terminal_backend?: string
personality?: string
running?: boolean
turn_started_at?: number | null
title?: string
stored_session_id?: string
desktop_contract?: number | string | null
version?: string
release_date?: string
update_behind?: unknown | null
update_command?: string
usage?: Usage | null
profile_name?: string | null
mcp_servers?: McpServerStatus[]
system_prompt?: string | null
credential_warning?: string | null
lazy?: boolean | null
[key: string]: unknown
}
/** ``tui_gateway/server.py::_project_info_for_cwd``. */
export interface ProjectRef {
id: string
slug: string
name: string
primary_path?: string | null
}
/** ``tui_gateway/server.py::_get_usage`` + ``agent/context_breakdown.py::context_usage_fields``. */
export interface Usage {
model?: string
input?: number
output?: number
reasoning?: number
prompt?: number
completion?: number
total?: number
calls?: number
compressions?: number | null
context_used?: number | null
context_max?: number | null
context_percent?: number | null
context_source?: string | null
context_estimated?: boolean | null
cache_hit_pct?: number | null
cache_read?: number | null
cache_write?: number | null
avg_latency_s?: number | null
avg_tps?: number | null
active_subagents?: number | null
dev_credits_spent_micros?: number | null
cost_usd?: number | null
cost_status?: string | null
plan_gauge?: PlanGauge | null
[key: string]: unknown
}
/** ``gateway/session_usage.py::plan_gauge``: a window plan's allowance for the status bar. */
export interface PlanGauge {
id: string
label: string
used_bp: number
resets_at_ms?: number | null
}
export interface McpServerStatus {
name?: string
status?: string | null
tool_count?: number | null
error?: string | null
[key: string]: unknown
}
/** ``provider_configured`` is the loose answer; the boot record's fields (``ready``, ``free_tier_account``, ``free_tier_route``, ``other_providers``, ``inference_provider``) ride along on the launch profile. An unknown ``profile`` answers ``ok=False`` + ``error``. */
export interface SetupStatusResult {
provider_configured?: boolean | null
ready?: boolean | null
free_tier_account?: boolean | null
free_tier_route?: boolean | null
other_providers?: boolean | null
inference_provider?: string | null
profile?: string | null
ok?: boolean | null
error?: string | null
error_code?: string | null
retryable?: boolean | null
retry_after?: number | null
}
export interface SetupRuntimeCheckParams {
profile?: string | null
provider?: string | null
}
/** ``ok=False`` + ``error`` when the resolved model can't be served; ``free_tier_route`` says the selected route is the welcome host. */
export interface SetupRuntimeCheckResult {
ok: boolean
provider?: string | null
model?: string | null
source?: string | null
error?: string | null
error_code?: string | null
free_tier_route?: boolean | null
profile?: string | null
}
export interface DiagnosticsShareNousParams {
error_context?: string | null
extra_files?: Record<string, string> | null
log_lines?: number | null
}
/** Structured envelope: ``ok=False`` + ``error`` renders inline instead of failing the RPC. */
export interface DiagnosticsShareNousResult {
ok: boolean
view_url?: string | null
upload_id?: string | null
expires_at?: string | null
error?: string | null
}
/** ``available`` = an identity exists AND the tier is on; whether inference runs on it is ``setup.runtime_check.free_tier_route``'s question. */
export interface FreeTierStatusResult {
has_guest: boolean
enabled: boolean
available: boolean
notice_pending: boolean
model: string
label: string
error?: string | null
error_code?: string | null
retryable?: boolean | null
retry_after?: number | null
challenge?: FreeTierChallengePayload | null
nudge_due_in?: number | null
connector_nudge_due_in?: number | null
}
/** ``hermes_cli/anon_challenge.py::BrowserChallenge.as_payload``: the ``free_tier.challenge`` event, and ``free_tier.status``'s ``challenge`` field for a client that connected after it. */
export interface FreeTierChallengePayload {
type: 'browser'
url: string
required: boolean
expires_in: number
message: string
attempt?: number
[key: string]: unknown
}
export interface FreeTierChallengeResultParams {
profile?: string | null
url: string
attempt?: number
outcome: 'done' | 'failed' | 'closed' | 'timeout' | 'refused' | 'error' | 'unsupported'
}
export interface FreeTierChallengeResult {
accepted: boolean
}
export interface FreeTierProvisionResult {
has_guest: boolean
enabled: boolean
error?: string | null
error_code?: string | null
retryable?: boolean | null
retry_after?: number | null
}
export interface FreeTierAckNoticeResult {
acked: boolean
}
export interface FreeTierClaimNudgeParams {
profile?: string | null
kind?: 'trial' | 'connector'
}
export interface FreeTierClaimNudgeResult {
claimed: boolean
}
/** The focused profile's ``telemetry.shared_metrics`` opt-ins. ``send`` is never true while ``enabled`` is false; ``decided`` = either key is written in config.yaml (the shipped defaults are not an answer) and it is not a ``reask``: an "off" from before the type-ahead fix, offered once more with the reason. */
export interface SharedMetricsConsentResult {
enabled: boolean
send: boolean
decided: boolean
reask?: boolean
}
/** ``send`` is ignored unless ``enabled``; ``first_run`` marks the Desktop first-run answer. */
export interface SharedMetricsSetParams {
profile?: string | null
enabled: boolean
send?: boolean
first_run?: boolean
}
/** ``command`` is the raw typed name (no leading ``/``, no args); the backend canonicalizes it against the published registry. ``session_id`` scopes the count to that session's profile. */
export interface SharedMetricsSlashCommandParams {
profile?: string | null
command: string
session_id?: string | null
}
export interface SharedMetricsSlashCommandResult {
ok: boolean
}
/** ``elapsed_ms`` = the client's own launch (TUI process start / Desktop app start) to ready (TUI gateway ready / Desktop backend attached), measured once per launch by the client. The client names its surface because a Desktop may attach to a URL/cloud backend where ``HERMES_DESKTOP`` is unset; without it the backend falls back to its own client detection. ``launch_id`` is an opaque per-launch token the backend latches on (never recorded), so a reconnect re-sending the same launch counts once while a new launch counts again. */
export interface SharedMetricsStartupLatencyParams {
profile?: string | null
elapsed_ms: number
surface?: 'desktop_attach' | 'tui' | null
launch_id?: string | null
}
export interface SharedMetricsStartupLatencyResult {
ok: boolean
}
/** One Desktop PACKAGED self-update (electron-updater / App Installer / Store). Source-checkout hand-offs run ``hermes update`` and are counted from its receipt, never here. Raw words; the backend buckets them: ``outcome`` success|failed|noop|refused, ``failed_stage`` download|verify|apply|restart, ``mechanism`` the updater strategy kind, ``duration_ms`` wall time, ``from_commit_date`` the updated-from build's commit time (epoch seconds) when known. */
export interface SharedMetricsUpdateRunParams {
profile?: string | null
outcome: string
failed_stage?: string | null
mechanism?: string | null
duration_ms?: number | null
from_commit_date?: number | null
}
export interface SharedMetricsUpdateRunResult {
ok: boolean
}
/** ``area`` is a Desktop surface id (``command_palette``, ``terminal_pane``, ``settings_<view>`` …); the backend collapses anything outside its closed set to ``other``. */
export interface SharedMetricsDesktopFeatureUseParams {
profile?: string | null
area: string
}
export interface OkResult {
ok?: boolean
}
/** ``kind`` notice_dismissed|error_toast|renderer_crash|backend_disconnect|slow_frame; ``detail`` a closed code-defined word for that kind (notice id, error category, crash reason, drop reason, frame duration bucket), never message text. */
export interface SharedMetricsDesktopFrictionParams {
profile?: string | null
kind: string
detail: string
}
/** ``step`` a Desktop first-run step id; ``event`` reached|completed|abandoned. */
export interface SharedMetricsDesktopOnboardingParams {
profile?: string | null
step: string
event: string
}
/** ``signal`` quick_close|cancelled|setting_off_default|rage_click|undo|feature_disabled; ``target`` a closed code-defined id for that signal (area, flow, action, undo path, feature toggle); ``setting`` a config key for setting_off_default only (the value is never sent — the backend compares it to the default). */
export interface SharedMetricsDesktopDislikeParams {
profile?: string | null
signal: string
target?: string
setting?: string | null
}
/** One finished UTC day of Desktop use, aggregated on the client. ``day`` (YYYY-MM-DD) only latches a resend and is never recorded; the raw counts are bucketed by the backend. */
export interface SharedMetricsDesktopDailyParams {
profile?: string | null
day: string
bot_count?: number
modes?: SharedMetricsDesktopModeDay[]
actions?: SharedMetricsDesktopActionDay[]
}
export interface SharedMetricsDesktopModeDay {
mode: 'bots' | 'sessions'
active_ms?: number
messages_sent?: number
}
export interface SharedMetricsDesktopActionDay {
action: string
via: 'click' | 'menu' | 'palette' | 'shortcut'
count: number
}
export interface SharedMetricsDesktopDailyResult {
recorded: boolean
}
export interface ModelOptionsParams {
profile?: string | null
session_id?: string | null
explicit_only?: boolean
include_unconfigured?: boolean
refresh?: boolean
}
export interface ModelOptionsResult {
providers: ModelOptionProvider[]
model?: string
provider?: string
}
/** One ``hermes_cli/inventory.py::build_models_payload`` provider row (the union of every field the builder sets; ``pricing_pending`` / ``free_tier_pending`` mark the cached-only path). */
export interface ModelOptionProvider {
slug: string
name: string
models?: string[]
total_models?: number | null
is_current?: boolean | null
is_user_defined?: boolean | null
source?: string | null
aliases?: string[] | null
api_url?: string | null
auth_type?: string | null
authenticated?: boolean | null
key_env?: string | null
warning?: string | null
featured_models?: string[] | null
capabilities?: Record<string, ModelCapabilities> | null
pricing?: Record<string, ModelPricing> | null
pricing_pending?: boolean | null
free_tier?: boolean | null
free_tier_pending?: boolean | null
free_tier_row?: boolean | null
unavailable_models?: string[] | null
plan_usage?: PlanUsage | null
usage_levels?: Record<string, string> | null
limit?: ProviderLimit | null
usage?: ProviderUsage | null
[key: string]: unknown
}
/** ``hermes_cli/inventory.py::_apply_capabilities``. */
export interface ModelCapabilities {
fast: boolean
ultrafast?: boolean
reasoning: boolean
can_disable_reasoning?: boolean | null
}
/** ``hermes_cli/inventory.py::_apply_pricing`` — formatted $/Mtok strings (``""`` unknown, ``"free"``); the sale fields are Nous Portal-only. */
export interface ModelPricing {
input: string
output: string
cache?: string | null
free: boolean
discount_percent?: number | null
was_input?: string | null
was_output?: string | null
}
/** ``hermes_cli/inventory.py::_apply_limits`` — ``account``: the whole login is rate-limited until ``resets_at`` (ISO, absent when unknown); ``models``: only these models are, each until its time. */
export interface ProviderLimit {
scope: 'account' | 'models'
resets_at?: string | null
models?: Record<string, string> | null
}
/** ``hermes_cli/inventory.py::_apply_usage`` — the provider's subscription usage, from cache. Multi-entry credential pools carry ``accounts`` (one row per account; the legacy ``windows`` stays EMPTY there — a provider-wide percentage across different logins would be fabricated). Single-account providers keep the legacy ``windows`` gauge. */
export interface ProviderUsage {
windows?: ProviderUsageWindow[]
accounts?: ProviderUsageAccount[] | null
}
/** One subscription usage window (``agent/account_usage.py::AccountUsageWindow``): e.g. the 5-hour session or the weekly cap, with how much of it is spent and when it rolls over (ISO). ``scope``: ``account`` — exhausting the window exhausts the whole login (Codex session/weekly, so a limited account's resets_at must wait for it); ``model`` — the window caps only one model family (Anthropic Opus/Sonnet weekly) and can never imply the account itself is out of quota. */
export interface ProviderUsageWindow {
label: string
used_percent: number
resets_at?: string | null
scope?: 'account' | 'model'
}
/** One account of a provider's credential pool (``hermes_cli/inventory.py::_pool_usage_accounts``). ``id`` is a stable non-secret account identity (never a key or URL); ``label`` may be empty (UI falls back to a localized "Account N"). ``windows`` is empty while the account's usage is not yet known — state carries the meaning, never a fabricated gauge. ``state``: ``ready`` — live quota below the cap (numeric windows present); ``limited`` — a live credential-wide cooldown or exhausted account-scoped quota windows; ``unknown`` — no live numeric windows (failed/empty fetch, stale snapshot, provider without a usage API); ``unavailable`` — DEAD auth row (kept visible, never a quota row). ``resets_at``: for a limited account, the LATEST of its exhausted account-scoped windows (or a live cooldown when later); ``None`` when unknown (the frontend renders its own advisory, e.g. the earliest limited sibling). */
export interface ProviderUsageAccount {
id: string
label?: string
windows?: ProviderUsageWindow[]
state: 'ready' | 'limited' | 'unknown' | 'unavailable'
resets_at?: string | null
}
export interface ImageGenerateParams {
prompt?: string | null
aspect_ratio?: string | null
probe?: unknown | null
max_bytes?: number | null
}
/** ``probe`` answers ``{available}`` alone; ``image_data`` (data URL) is omitted when the download failed or exceeded ``max_bytes`` so callers fall back to ``image``. */
export interface ImageGenerateResult {
available: boolean
success?: boolean | null
image?: string | null
image_data?: string | null
error?: string | null
}
export interface SessionControlReadParams {
profile?: string | null
session_id: string
}
export interface SessionControlReadResult {
control: SessionControlSnapshot
}
/** ``_snapshot_control`` — ``revision`` is a hash of the visible state (``""`` when empty); ``updated_at`` is the newest persisted timestamp (``0`` when none). */
export interface SessionControlSnapshot {
goal: GoalSnapshot | null
loop: LoopSnapshot | null
heartbeat: HeartbeatSnapshot | null
revision: string
updated_at: number
}
/** ``methods_session_control.py::_safe_goal_snapshot`` — the frontend-safe GoalState subset. */
export interface GoalSnapshot {
title: string
status: string
turns_used: number
max_turns: number
contract: GoalContractSnapshot
subgoals: string[]
gates: GoalGateSnapshot[]
created_at?: number | null
updated_at?: number | null
paused_reason?: string | null
last_verdict?: string | null
last_reason?: string | null
wait_barrier?: WaitBarrierUntil | WaitBarrierTarget | null
}
/** ``hermes_cli/goals.py::GoalContract.to_dict``. */
export interface GoalContractSnapshot {
outcome?: string
verification?: string
constraints?: string
boundaries?: string
stop_when?: string
}
export interface GoalGateSnapshot {
command: string
timeout_seconds: number
max_retries: number
attempts: number
last_exit_code?: number | null
}
export interface WaitBarrierUntil {
type: 'until'
until_at: number
reason?: string
}
export interface WaitBarrierTarget {
type: 'session' | 'pid'
target: string | number
reason?: string
}
/** ``_safe_loop_snapshot`` — persisted LoopState fields, never its route. */
export interface LoopSnapshot {
prompt: string
status: string
mode: string
interval_seconds: number
current_delay: number
times: number
until: string
max_ticks: number
ticks_fired: number
created_at: number
last_fired_at: number
next_due_at: number
awaiting_response: boolean
deferred_by_goal: boolean
paused_reason?: string | null
last_stop_reason?: string | null
}
export interface HeartbeatSnapshot {
prompt: string
status: string
interval_seconds: number
created_at: number
last_fired_at: number
fire_count: number
}
/** ``action`` is validated by the handler (unknown / gate actions answer ``4004``), so it stays a string on the wire; ``SessionControlAction`` lists the accepted set. */
export interface SessionControlParams {
profile?: string | null
session_id: string
action: string
args?: SessionControlArgs | null
}
/** ``subgoal.add`` reads ``text``; ``subgoal.remove`` reads the 1-based ``index``. */
export interface SessionControlArgs {
text?: string | null
index?: number | null
}
export interface SessionControlResult {
control: SessionControlSnapshot
dispatch: SessionControlDispatch
}
/** ``_dispatch_envelope`` — the command result's user-visible envelope, every key always present. */
export interface SessionControlDispatch {
type: string | null
output: string | null
notice: string | null
message: string | null
display: string | null
}
export interface VerificationStatusParams {
profile?: string | null
session_id?: string | null
session_key?: string | null
cwd?: string | null
}
export interface VerificationStatusResult {
verification: VerificationStatusInfo
}
/** ``verification_status()``: ``disabled`` / ``not_applicable`` / ``unverified`` / ``stale`` or the latest event's own status; ``root`` and friends only once a workspace was identified. */
export interface VerificationStatusInfo {
status: string
evidence?: VerificationEvidenceRow | null
root?: string | null
session_id?: string | null
changed_paths?: string[] | null
}
/** One ``verification_events`` row (``agent/verification_evidence.py``). */
export interface VerificationEvidenceRow {
id?: number | null
created_at?: string | null
session_id?: string | null
cwd?: string | null
root?: string | null
command?: string | null
canonical_command?: string | null
kind?: string | null
scope?: string | null
status?: string | null
exit_code?: number | null
output_summary?: string | null
[key: string]: unknown
}
export interface ConnectionOperationParams {
profile?: string | null
owner: SessionOwner | AccountOwner
op_id: string
}
export interface SessionOwner {
type: 'session'
session_id: string
}
export interface AccountOwner {
type: 'account'
}
/** ``methods_connectors._operation_view``: the operation's full snapshot. */
export interface ConnectionOperationStatus {
op_id: string
seq: number
deadline_at: number
settled: boolean
settled_at?: number | null
settled_by?: ConnectionSettleReason | null
targets: ConnectionOperationTarget[]
}
/** ``tools/connectors/contract.py::SettleReason``. */
export type ConnectionSettleReason = 'all_resolved' | 'continue' | 'deadline' | 'interrupt'
/** ``Target.snapshot``: the link minted up front rides here, never in the model result. ``extra`` keys a leg records (``tools``, ``hint``) are typed here as they appear. */
export interface ConnectionOperationTarget {
name: string
kind: ConnectionTargetKind
action: ConnectionTargetAction
state: ConnectionTargetState
resolved?: boolean | null
detail?: string | null
instructions?: string | null
discovery_error?: string | null
connect_url?: string | null
connection_id?: string | null
alias?: string | null
attempt?: string | null
required_env?: ConnectionTargetEnvField[] | null
tools?: string[] | null
hint?: string | null
display?: string | null
description?: string | null
tier?: CatalogTier | null
platforms?: string[] | null
repo?: string | null
sha?: string | null
subdir?: string | null
scan?: CatalogScan | null
requires_hermes?: string | null
has_desktop_half?: boolean | null
target_profile?: string | null
app_state?: CatalogAppState | null
skill?: string | null
phase?: InstallPhase | null
approved?: CatalogApproved | null
enabled?: boolean | null
missing_env?: string[] | null
server_errors?: CatalogServerError[] | null
already_installed?: boolean | null
}
export type ConnectionTargetKind = 'connector' | 'mcp' | 'plugin' | 'skill'
export type ConnectionTargetAction = 'authorize' | 'connect' | 'enable' | 'install' | 'reconnect'
/** ``tools/connectors/contract.py::TargetState``. */
export type ConnectionTargetState = 'pending' | 'initiated' | 'connected' | 'skipped' | 'failed' | 'expired' | 'not_connected'
/** One credential an MCP install still needs; the card renders a field per entry and sends the values back with the approval. */
export interface ConnectionTargetEnvField {
name: string
required: boolean
secret: boolean
default: string
prompt?: string | null
}
export type CatalogTier = 'official' | 'verified' | 'community'
/** The catalog's security scan of the pinned commit; read-only on the card. */
export interface CatalogScan {
status: CatalogScanStatus
summary: string
}
export type CatalogScanStatus = 'passed' | 'warnings' | 'failed'
/** The desktop app a catalog plugin drives, from its ``hermes_platform`` declaration. */
export type CatalogAppState = 'present' | 'missing_app' | 'app_not_running' | 'unknown'
/** The slow steps of an install, as ids; the desktop catalog card words them in its own language. */
export type InstallPhase = 'downloading' | 'python_packages' | 'loading_tools'
/** The non-secret Advanced choices the user approved on a catalog row; a Try again after the operation settled repeats them. */
export interface CatalogApproved {
force: boolean
enable: boolean
ref?: string | null
}
/** An MCP server an installed plugin brought that did not connect, with the raw reason. */
export interface CatalogServerError {
name: string
error: string
}
export interface ConnectionWakeResult {
status: 'ok'
}
export interface ConnectionRespondParams {
profile?: string | null
owner: SessionOwner | AccountOwner
op_id: string
result: ConnectionAnswer
}
/** The card's answer: per-target outcomes and an optional Continue (``settled_by: "continue"``). Settlement is derived from target states afterwards. */
export interface ConnectionAnswer {
targets?: ConnectionAnswerTarget[]
settled_by?: ConnectionSettleReason | null
said?: string | null
}
/** One row's answer from the card. ``env`` carries the credential values an install asked for through ``required_env``. */
export interface ConnectionAnswerTarget {
name: string
status: ConnectionAnswerStatus
detail?: string | null
env?: Record<string, string> | null
}
/** What the card says about one row: ``tools/connectors/mcp.py::apply_answer``. */
export type ConnectionAnswerStatus = 'approved' | 'skipped'
export interface ConnectionRespondResult {
status: 'ok'
settled: boolean
}
export interface ConnectorsListParams {
profile?: string | null
owner: SessionOwner | AccountOwner
}
export interface ConnectorsListResult {
available: boolean
connectors: ConnectorRow[]
}
export interface ConnectorRow {
connector: string
enabled: boolean
connected: boolean
connection_status: 'pending' | 'active' | 'failed' | 'expired' | 'revoked' | 'inactive' | null
status_reason: string | null
gateway_disabled_tools: string[]
}
export interface ConnectorsConnectParams {
profile?: string | null
owner: SessionOwner | AccountOwner
connectors: string[]
reconnect?: boolean
alias?: string | null
connection_id?: string | null
}
/** ``methods_connectors._reissue`` / ``managed._off_desktop_result``: the operation the connect opened; ``status``/``note`` ride along from the tool result. */
export interface ConnectorsConnectResult {
op_id: string
seq: number
deadline_at: number
settled: boolean
settled_at?: number | null
settled_by?: ConnectionSettleReason | null
targets: ConnectionOperationTarget[]
status?: 'initiated' | 'settled' | null
note?: string | null
}
export interface ConnectorToolsParams {
profile?: string | null
slug: string
refresh?: boolean
}
export interface ConnectorToolsResult {
connector: string
toolkit_version: string
etag: string
fetched_at: number
source: ConnectorToolsSource
stale: boolean
tools: ConnectorToolRow[]
}
export type ConnectorToolsSource = 'cache' | 'network' | 'revalidated'
export interface ConnectorToolRow {
slug: string
name: string
description: string
facet: ConnectorToolFacet
hints: string[]
categories: string[]
no_auth: boolean
deprecated: boolean
}
export type ConnectorToolFacet = 'read' | 'write' | 'destructive' | 'unclassified'
export interface ConnectorsCatalogResult {
connectors: ConnectorCatalogRow[]
}
export interface ConnectorCatalogRow {
slug: string
name: string
description: string
category: string
logo_url?: string | null
}
export interface ConnectorAccountsParams {
profile?: string | null
connector?: string | null
}
export interface ConnectorAccountsResult {
accounts: ConnectorAccountRow[]
}
export interface ConnectorAccountRow {
connection_id: string
connector: string
status: ConnectorAccountStatus
status_reason?: string | null
label: string
alias?: string | null
active: boolean
disabled?: boolean
created_at: string
updated_at: string
}
export type ConnectorAccountStatus = 'pending' | 'active' | 'failed' | 'expired' | 'revoked' | 'inactive'
export interface ConnectorAccountsRemoveParams {
profile?: string | null
connection_id: string
}
export interface ConnectorAccountsRemoveResult {
connection_id: string
connector: string
status: 'removed'
}
export interface ConnectorAccountsRenameParams {
profile?: string | null
connection_id: string
alias: string
}
export interface ConnectorPolicyGetResult {
layers: ConnectorPolicyLayer[]
effective: ConnectorPolicyEffectiveUnrestricted | ConnectorPolicyEffectiveDenyAll | ConnectorPolicyEffectiveAllow | ConnectorPolicyEffectiveDeny
}
export interface ConnectorPolicyLayer {
kind: ConnectorPolicyLayerKind
revision: string
body: ConnectorPolicyUnrestrictedBody | ConnectorPolicyDenyAllBody | ConnectorPolicyAllowBody | ConnectorPolicyDenyBody
}
export type ConnectorPolicyLayerKind = 'org' | 'role' | 'member'
export interface ConnectorPolicyUnrestrictedBody {
mode: 'unrestricted'
}
export interface ConnectorPolicyDenyAllBody {
mode: 'deny-all'
}
export interface ConnectorPolicyAllowBody {
mode: 'allow'
connectors: string[]
tools: Record<string, string[]>
tags?: ConnectorPolicyTags | null
}
export interface ConnectorPolicyTags {
enable?: string[] | null
disable?: string[] | null
}
export interface ConnectorPolicyDenyBody {
mode: 'deny'
disabled_connectors: string[]
tools: Record<string, string[]>
tags?: ConnectorPolicyTags | null
}
export interface ConnectorPolicyEffectiveUnrestricted {
version: 1
revision: string
issued_at_ms: number
mode: 'unrestricted'
}
export interface ConnectorPolicyEffectiveDenyAll {
version: 1
revision: string
issued_at_ms: number
mode: 'deny-all'
}
export interface ConnectorPolicyEffectiveAllow {
version: 1
revision: string
issued_at_ms: number
mode: 'allow'
connectors: string[]
tools: Record<string, string[]>
tags?: ConnectorPolicyTags | null
}
export interface ConnectorPolicyEffectiveDeny {
version: 1
revision: string
issued_at_ms: number
mode: 'deny'
disabled_connectors: string[]
tools: Record<string, string[]>
tags?: ConnectorPolicyTags | null
}
export interface ConnectorPolicySetParams {
profile?: string | null
change: ToolsChange | ConnectorChange
expected_revision: string
}
export interface ToolsChange {
type: 'tools'
connector: string
disabled_tools: string[]
}
export interface ConnectorChange {
type: 'connector'
connector: string
enabled: boolean
}
export interface ConnectorPolicySetResult {
revision: string
effective: ConnectorPolicyEffectiveUnrestricted | ConnectorPolicyEffectiveDenyAll | ConnectorPolicyEffectiveAllow | ConnectorPolicyEffectiveDeny
}
/** ``tools/bot_desktop/runtime.py::DesktopStatus`` plus the lease and the profile it speaks for. */
export interface DisplayStatus {
profile: string
supported: boolean
installed: boolean
missing: string[]
running: boolean
pid?: number | null
display?: string | null
socket?: string | null
geometry: string
install_command?: string | null
browser?: string | null
blocker?: string | null
memory_available_mb?: number | null
memory_limit_mb?: number | null
placement?: string
image_switch?: DisplayImageSwitch | null
lease: DisplayLease
profile_key: string
}
/** A persisted Docker sandbox kept on the previous default image; the user decides the switch. */
export interface DisplayImageSwitch {
current_image: string
target_image: string
containers: number
}
/** ``tools/bot_desktop/lease.py::Lease`` as clients may see it: the holder's viewer id is a capability and never leaves the gateway; ``viewer_hash`` lets the holder recognise itself. */
export interface DisplayLease {
holder: LeaseHolder
viewer_id?: null
viewer_hash?: string | null
since: number
epoch: number
reason?: string
}
export type LeaseHolder = 'agent' | 'human'
/** ``data_url`` is null while the screen is stopped or while a human holds the lease (``suppressed``): the frame may show what they are typing. */
export interface DisplayThumbnailResult {
data_url?: string | null
suppressed?: string | null
}
export interface DisplayStopParams {
profile?: string | null
force?: boolean | null
}
export interface DisplayStopResult {
profile: string
supported: boolean
installed: boolean
missing: string[]
running: boolean
pid?: number | null
display?: string | null
socket?: string | null
geometry: string
install_command?: string | null
browser?: string | null
blocker?: string | null
memory_available_mb?: number | null
memory_limit_mb?: number | null
placement?: string
image_switch?: DisplayImageSwitch | null
lease: DisplayLease
profile_key: string
stopped: boolean
}
export interface DisplayObserveParams {
profile?: string | null
viewer_id?: string | null
}
export interface DisplayObserveResult {
profile: string
supported: boolean
installed: boolean
missing: string[]
running: boolean
pid?: number | null
display?: string | null
socket?: string | null
geometry: string
install_command?: string | null
browser?: string | null
blocker?: string | null
memory_available_mb?: number | null
memory_limit_mb?: number | null
placement?: string
image_switch?: DisplayImageSwitch | null
lease: DisplayLease
profile_key: string
ticket: string
path: string
viewer_id: string
}
export interface DisplaySwitchSandboxImageParams {
profile?: string | null
approve?: boolean
}
export interface DisplaySwitchSandboxImageResult {
profile: string
supported: boolean
installed: boolean
missing: string[]
running: boolean
pid?: number | null
display?: string | null
socket?: string | null
geometry: string
install_command?: string | null
browser?: string | null
blocker?: string | null
memory_available_mb?: number | null
memory_limit_mb?: number | null
placement?: string
image_switch?: DisplayImageSwitch | null
lease: DisplayLease
profile_key: string
docker_image: string
}
export interface DisplayInstallResult {
started: boolean
command?: string | null
profile_key: string
}
export interface DisplayLeaseAcquireParams {
profile?: string | null
viewer_id: string
reason?: string | null
}
export interface DisplayLeaseResult {
lease: DisplayLease
}
export interface DisplayLeaseReleaseParams {
profile?: string | null
viewer_id?: string | null
force?: boolean | null
}
export interface GroupsCapabilitiesParams {
profile?: string | null
}
export interface GroupsCapabilitiesResult {
protocol_version: number
driver: boolean
persistent_process: boolean
authority_gateway_id: string
room_link: RoomLinkStatus
features: string[]
methods: string[]
max_log_limit: number
seatable_profiles?: string[] | null
}
/** ``enabled`` with ``profile``/``catalog``/``endpoint``, or disabled with a ``reason``. */
export interface RoomLinkStatus {
enabled: boolean
profile?: string | null
catalog?: RoomLinkCatalog | null
endpoint?: RoomLinkEndpoint | null
reason?: string | null
}
/** ``gateway/hosted_room_peer.py::GatewayRoomCatalog.as_mapping``. */
export interface RoomLinkCatalog {
installation_id: string
protocol_versions: number[]
link_modes: string[]
persistent_process: boolean
text: boolean
attachments: boolean
execution_policy: RoomExecutionPolicy
catalog_digest: string
endpoint?: RoomLinkEndpoint | null
}
/** ``gateway/hosted_room_execution_policy.py::execution_policy_mapping``. */
export interface RoomExecutionPolicy {
version: number
target_profile: string
enabled_toolsets: string[]
approval_mode: string
max_iterations: number
policy_digest: string
}
/** ``GatewayRoomCatalog.endpoint_mapping``: ``url``/``transport_security`` when available, ``reason`` when not. */
export interface RoomLinkEndpoint {
available: boolean
url?: string | null
transport_security?: string | null
reason?: string | null
}
export interface GroupsListParams {
profile?: string | null
include_disbanded?: boolean | null
limit?: number | null
offset?: number | null
}
export interface GroupsListResult {
rooms: Room[]
next_offset?: number | null
}
/** ``gateway/hosted_rooms.py::_room_from_row`` plus the branch-only keys ``create`` (legacy adoption), ``state`` (``authority_claim``) and ``rename`` (``event``) add. */
export interface Room {
room_id: string
name: string
members: RoomMember[]
authority_gateway_id: string
authority_epoch: number
revision: number
created_at: number
updated_at: number
idempotent?: boolean
disbanded_at?: number | null
latest_seq?: number | null
adopted?: boolean | null
claim_event?: RoomEvent | null
authority_claim?: RoomEvent | null
event?: RoomEvent | null
}
/** One roster row (``hosted_room_discussion.validate_roster``); legacy rooms may carry pre-normalisation rows, so the set stays open. */
export interface RoomMember {
member_id?: string | null
profile?: string | null
handle?: string | null
display_name?: string | null
target?: Record<string, unknown> | null
[key: string]: unknown
}
/** ``gateway/hosted_rooms.py::_event_from_row``. */
export interface RoomEvent {
room_id: string
seq: number
event_id: string
kind: string
actor: RoomActor
authority_epoch?: number | null
payload: Record<string, unknown>
created_at: number
idempotent?: boolean
}
/** ``hosted_rooms._ACTOR_FIELDS``; member replies carry ``profile`` plus, when known, ``display_name`` and the peer ``connection_id`` (``hosted_room_discussion._member_actor``). */
export interface RoomActor {
kind: string
id: string
profile?: string | null
display_name?: string | null
connection_id?: string | null
}
export interface GroupsCreateParams {
profile?: string | null
room_id: string
name: string
members: RoomMemberInput[]
authority_gateway_id?: string | null
}
/** A roster row as the client proposes it; ``validate_roster`` owns the exact rules. */
export interface RoomMemberInput {
member_id?: string | null
profile?: string | null
handle?: string | null
display_name?: string | null
target?: Record<string, unknown> | null
[key: string]: unknown
}
export interface GroupsCreateResult {
room: Room
}
export interface GroupsStateParams {
profile?: string | null
room_id: string
include_disbanded?: boolean | null
}
export interface GroupsStateResult {
room: Room
driver_status?: RoomDriverStatus | null
}
/** ``HostedRoomService.status(room_id)``; ``pending_actions`` rows are the exact attempt (``hosted_room_service.attempt_action``: ``kind`` + ``member_id``/``task_id``/``execution_generation``) or the driver's approval action (``kind: approval`` + run/session/approval context), or a stalled room preparation's Retry (``task_id`` ``prepare:<room_id>``, ``member_id`` the members not woken). ``member_activity`` lists live tasks in admission order (absent from older gateways). ``last_error`` is this room's last preparation failure, null once one succeeds. */
export interface RoomDriverStatus {
running: boolean
working: boolean
blocked: boolean
counts: Record<string, number>
pending_actions: Record<string, unknown>[]
member_activity?: RoomMemberActivity[]
last_error?: string | null
peer_routes: PeerRouteStatus[]
}
/** One live room task: ``status`` is ``queued``, ``running`` or ``stopping``. */
export interface RoomMemberActivity {
member_id: string
status: string
}
export interface PeerRouteStatus {
room_id: string
member_id: string
status: string
}
export interface GroupsSendParams {
profile?: string | null
room_id: string
event_id?: string | null
payload: Record<string, unknown>
}
export interface GroupsSendResult {
event: RoomEvent
client_event_id?: string | null
accepted?: boolean
driver_started?: boolean
}
export interface GroupsRenameParams {
profile?: string | null
room_id: string
event_id: string
name: string
}
export interface GroupsRenameResult {
room: Room
}
export interface GroupsLogParams {
profile?: string | null
room_id: string
since_seq?: number | null
limit?: number | null
include_disbanded?: boolean | null
}
/** ``gateway/hosted_rooms.py::read_events`` page — also the ``page`` ``groups.replicate`` ingests. */
export interface GroupsLogResult {
events: RoomEvent[]
cursor: number
latest_seq: number
has_more: boolean
authority: RoomAuthority
}
export interface RoomAuthority {
gateway_id: string
epoch: number
}
export interface GroupsDisbandParams {
profile?: string | null
room_id: string
cancel_id?: string | null
}
export interface GroupsDisbandResult {
tombstone: RoomTombstone
}
export interface RoomTombstone {
room_id: string
disbanded_at: number
idempotent: boolean
history_expired?: boolean | null
event?: RoomEvent | null
}
export interface GroupsStopParams {
profile?: string | null
room_id: string
cancel_id?: string | null
}
export interface GroupsStopResult {
cancelled: number
}
export interface GroupsApproveParams {
profile?: string | null
room_id: string
member_id: string
task_id: string
execution_generation: number
choice: ApprovalChoice
request_id: string
}
export type ApprovalChoice = 'once' | 'session' | 'always' | 'deny'
/** ``result`` is the local ``approval.respond`` answer or the peer's run-action receipt. */
export interface GroupsApproveResult {
approved?: boolean
result: Record<string, unknown>
}
export interface GroupsRetryParams {
profile?: string | null
room_id: string
task_id: string
member_id?: string | null
execution_generation?: number | null
}
export interface GroupsRetryResult {
retried?: boolean
task: RoomTaskReceipt
}
export interface RoomTaskReceipt {
room_id: string
task_id: string
thread_id: string
turn_id: string
status: string
execution_generation: number
cancel_generation: number
}
export interface GroupsReplicateParams {
profile?: string | null
room_id: string
room_name: string
members: RoomMemberInput[]
page: Record<string, unknown>
}
export interface GroupsReplicateResult {
room_id: string
stored_seq: number
ingested: number
authority: RoomAuthority
caught_up: boolean
}
export interface GroupsReplicaStateParams {
profile?: string | null
room_id: string
}
export interface GroupsReplicaStateResult {
room_id: string
name: string
members: RoomMember[]
authority: RoomAuthority
last_seq: number
latest_seq: number
event_bytes: number
created_at: number
updated_at: number
}
export interface GroupsPromoteParams {
profile?: string | null
room_id: string
confirm?: boolean | null
reason?: string | null
}
export interface GroupsPromoteResult {
room_id: string
authority_gateway_id: string
authority_epoch: number
previous_gateway_id: string
previous_epoch: number
claim_seq: number
latest_seq: number
}
export interface GroupsDemoteParams {
profile?: string | null
room_id: string
observed_gateway_id: string
observed_epoch: number
}
export interface GroupsDemoteResult {
room_id: string
authority_gateway_id: string
authority_epoch: number
idempotent: boolean
}
export interface GroupsPeerInviteParams {
profile?: string | null
room_id?: string | null
home_install_id?: string | null
authority_gateway_id?: string | null
authority_epoch?: number | null
member_id?: string | null
grant_id?: string | null
ttl_seconds?: number | null
}
export interface GroupsPeerInviteResult {
grant: string
target_profile: string
catalog: RoomLinkCatalog
endpoint: RoomLinkEndpoint
}
export interface GroupsPeerRevokeParams {
profile?: string | null
grant: string
}
export interface GroupsPeerRevokeResult {
revoked?: boolean
}
export interface GroupsPeerRegisterParams {
profile?: string | null
room_id: string
member_id: string
target_url: string
target_profile: string
grant: string
catalog: Record<string, unknown>
cancellation_scope_id?: string | null
trace_id?: string | null
}
export interface GroupsPeerRegisterResult {
registered?: boolean
mode: string
transport_security: string
target_install_id: string
target_profile: string
}
export interface BotRelayRosterSyncParams {
profile?: string | null
agents?: RelayAgentRow[] | null
}
/** A roster row the Desktop pushes (``tools/bot_relay.py::_normalize_roster_row``); invalid rows are dropped server-side, so the shape stays open. */
export interface RelayAgentRow {
profile?: string | null
handle?: string | null
connection_id?: string | null
connection_label?: string | null
title?: string | null
description?: string | null
online?: boolean | null
[key: string]: unknown
}
export interface BotRelayRosterSyncResult {
count: number
}
export interface BotRelayOutboxDrainParams {
profile?: string | null
}
export interface BotRelayOutboxDrainResult {
envelopes: RelayEnvelope[]
}
/** ``tools/bot_relay.py::enqueue_envelope``. */
export interface RelayEnvelope {
id: string
created_at: number
from_profile: string
from_handle: string
target_connection: string
target_profile: string
target_handle: string
message: string
[key: string]: unknown
}
/** ``profile`` here is the TARGET profile on this gateway (also what the desktop route wrapper adds). */
export interface BotRelayDeliverParams {
profile: string
message: string
from_profile?: string | null
from_handle?: string | null
from_connection?: string | null
}
export interface BotRelayDeliverResult {
reply: string
}
export interface BotRelayReplyParams {
profile?: string | null
id: string
reply?: string | null
error?: string | null
reason?: string | null
}
export interface I18nLanguagesResult {
languages: LanguageOption[]
}
/** ``agent.i18n_languages.language_options`` row. ``source`` is ``bundled``, ``overlay`` or ``plugin:<name>`` — the highest layer that supplies the language. ``surfaces`` are the surfaces some layer has strings for; a renderer leaves out a language it does not bundle and that lacks its surface, since picking it would only show English. */
export interface LanguageOption {
id: string
endonym: string
rtl: boolean
source: string
surfaces: LocaleSurface[]
}
export type LocaleSurface = 'core' | 'tui' | 'desktop'
export interface I18nCatalogParams {
profile?: string | null
lang: string
surface?: LocaleSurface
}
/** ``messages`` is ONLY the pack + user-overlay layer for that surface (flat dotted keys); the client merges it over its bundled ``en``/``<lang>``. ``lang`` is the canonical id the request resolved to (``pt-BR`` → ``pt-br``; an unknown id resolves to ``en`` with an empty layer). */
export interface I18nCatalogResult {
lang: string
surface: LocaleSurface
messages: Record<string, string>
}
export type PingParams = Record<string, never>
export interface PingResult {
pong: boolean
}
export interface GatewayCapabilitiesResult {
per_session_exclusive_submit: boolean
}
export interface ClientCapabilitiesParams {
server_requests?: boolean
desktop_local?: boolean
}
export interface ClientCapabilitiesResult {
server_requests: string[]
declines_not_shown?: boolean
canonical_clarify_batch?: boolean
}
/** Client→server method params / server→client request params. Unknown keys are rejected. */
export type Params = Record<string, never>
/** ``machine_kind`` is ``Spark``, ``Mac``, ``PC`` or ``computer``. ``nvidia_platform`` is ``products.nvidia_platform()``: ``rtx_spark``, ``dgx_spark``, ``discrete`` or null. ``locale`` is the OS account's first UI language, null when the OS has none. */
export interface MachineFactsResult {
machine: MachineInfo
machine_kind: string
has_nvidia_gpu: boolean
nvidia_platform?: 'rtx_spark' | 'dgx_spark' | 'discrete' | null
locale?: string | null
}
/** Measured hardware; a key that was not measured is absent. */
export interface MachineInfo {
os_family?: string | null
os_release?: string | null
native_arch?: string | null
cpu_model?: string | null
ram_gb?: number | null
gpu_class?: string | null
vendor?: string | null
wsl?: boolean | null
container?: boolean | null
}
/** ``word`` is the token under the cursor (``@`` prefix = context reference); ``cwd`` / ``session_id`` pick the directory the listing resolves against. */
export interface CompletePathParams {
profile?: string | null
word?: string | null
cwd?: string | null
session_id?: string | null
}
export interface CompletionItemsResult {
items?: CompletionItem[]
}
/** One popover row; ``kind`` rides only on slash completions (command vs skill). */
export interface CompletionItem {
text: string
display?: string
meta?: string
kind?: string | null
}
/** ``session_id`` binds skill completions to that session's profile and workspace (project skills); ``profile`` scopes a session-less request (a new-chat draft). */
export interface CompleteSlashParams {
text?: string | null
session_id?: string | null
profile?: string | null
}
/** ``replace_from`` is the column the accepted item replaces from. */
export interface CompleteSlashResult {
items?: CompletionItem[]
replace_from?: number | null
}
export interface PasteCollapseParams {
text?: string | null
}
export interface PasteCollapseResult {
placeholder: string
path: string
lines: number
}
export interface ModelSaveKeyParams {
slug: string
api_key: string
session_id?: string | null
}
export interface ModelSaveKeyResult {
provider: ModelOptionProvider
}
export interface ModelDisconnectParams {
slug: string
session_id?: string | null
}
export interface ModelDisconnectResult {
slug: string
name: string
disconnected: boolean
}
export interface ProfilesListParams {
profile?: string | null
include_sessions?: boolean | string | null
}
/** ``bot_mode_protocol`` tells clients this backend injects the teammate protocol itself; ``install_id`` (as on ``/api/status``) names the machine that answered. */
export interface ProfilesListResult {
profiles?: ProfileRow[]
bot_mode_protocol?: boolean
install_id?: string
}
/** One roster row; the session fields are present only with ``include_sessions``. */
export interface ProfileRow {
name: string
path: string
is_default?: boolean
model?: string | null
provider?: string | null
description?: string
display_name?: string
skill_count?: number
previous_names?: string[]
last_session?: ProfileSessionPreview | null
worker_session?: ProfileWorkerSession | null
canonical_session?: ProfileCanonicalSession | null
ui_meta_revisions?: Record<string, number>
ui_meta?: Record<string, unknown> | null
has_avatar?: boolean
}
/** Newest human-facing session of a profile (``_latest_profile_session_rows``). */
export interface ProfileSessionPreview {
id: string
title?: string
preview?: string
started_at?: number
last_active?: number
message_count?: number
live_message_count?: number | null
}
/** Newest kanban/tool worker row, so rosters can show a profile as working. */
export interface ProfileWorkerSession {
id: string
source?: string
title?: string
last_active?: number
}
/** The profile's "Bot Chat" registry row; ``resolved_id`` is the live compression tip. */
export interface ProfileCanonicalSession {
id: string
resolved_id: string
root_title?: string
title?: string
preview?: string
started_at?: number
last_active?: number
message_count?: number
live_message_count?: number | null
}
/** ``clone_from`` omitted = fresh profile + bundled skills; ``mirror_credentials`` defaults on so a headless bot has a provider. */
export interface ProfilesCreateParams {
profile?: string | null
name: string
description?: string | null
clone_from?: string | null
clone_all?: boolean | string | null
clone_channels?: boolean | string | null
no_skills?: boolean | string | null
no_alias?: boolean | string | null
soul?: string | null
model?: string | null
provider?: string | null
share_auth?: boolean | string | null
mirror_credentials?: boolean | string | null
}
export interface ProfilesCreateResult {
ok?: boolean
name: string
path: string
soul_written?: boolean
model_set?: boolean
mirrored: ProfileMirrored
}
/** What was copied from the launch profile; ``auth`` is ``"shared"`` under ``share_auth``. */
export interface ProfileMirrored {
env?: boolean
auth?: boolean | 'shared'
model_inherited?: boolean
voice?: boolean
}
export interface ProfileNameParams {
profile?: string | null
name?: string | null
}
/** Editor snapshot; ``toolsets_pinned`` says whether ``tools.enabled_toolsets`` is explicit. */
export interface ProfilesDescribeResult {
name: string
description?: string
soul?: string
model: ProfileModelPin
skills?: CapabilityEntry[]
toolsets?: ToolsetEntry[]
toolsets_pinned?: boolean
mcp_servers?: McpServerEntry[]
}
export interface ProfileModelPin {
provider?: string
default?: string
}
export interface CapabilityEntry {
name: string
enabled?: boolean
}
export interface ToolsetEntry {
name: string
enabled?: boolean
label?: string
description?: string
tool_count?: number
}
export interface McpServerEntry {
name: string
enabled?: boolean
transport?: string
}
/** Sections are independent; ``ui_meta_expected_revisions`` is a per-key compare-and-swap. */
export interface ProfilesConfigureParams {
profile?: string | null
name?: string | null
ui_meta?: Record<string, unknown> | null
ui_meta_expected_revisions?: Record<string, number> | null
soul?: string | null
description?: string | null
model?: string | null
provider?: string | null
confirm_expensive_model?: boolean | string | null
disabled_skills?: string[] | null
enabled_toolsets?: string[] | null
enabled_mcp_servers?: string[] | null
}
/** ``confirm_required`` mirrors ``config.set``: a guarded model pick wrote nothing yet. */
export interface ProfilesConfigureResult {
ok: boolean
applied: ProfilesConfigureApplied
confirm_required?: boolean | null
confirm_message?: string | null
}
/** Per-section outcome; only the sections the request carried are present. */
export interface ProfilesConfigureApplied {
ui_meta?: boolean | null
ui_meta_revisions?: Record<string, number> | null
ui_meta_conflicts?: Record<string, UiMetaConflict> | null
soul?: boolean | null
description?: boolean | null
model?: boolean | null
skills?: boolean | null
toolsets?: boolean | null
mcp_servers?: boolean | null
}
export interface UiMetaConflict {
expected?: unknown
actual?: number
}
/** ``data`` is a data URL or bare base64 (PNG/JPEG/WebP, sniffed); ``clear`` deletes instead. */
export interface ProfilesSetAssetParams {
profile?: string | null
name?: string | null
asset?: string | null
data?: string | null
clear?: boolean | string | null
}
export interface ProfilesSetAssetResult {
ok?: boolean
asset: string
size?: number
removed?: number | null
}
export interface ProfilesGetAssetParams {
profile?: string | null
name?: string | null
asset?: string | null
}
/** Absent is ``found: false``, not an error. */
export interface ProfilesGetAssetResult {
found: boolean
mime?: string | null
size?: number | null
data?: string | null
}
/** ``assume_fresh``: the unpackaged desktop's ``--fresh-install`` launch; the backend treats this machine as one that never used Hermes. Packaged builds never send it. */
export interface OnboardingStateParams {
assume_fresh?: boolean
}
/** ``run``: onboarding opens on this launch (root config ``onboarding.run``, else a machine that never used Hermes). ``eligible``: this is the desktop's local backend and the welcome trial or a configured provider can carry the first chat. ``session_id``: the stored id of the onboarding chat still in progress, so a relaunch reopens it; ``run_id``: that run's id, which ``onboarding.ended`` names. */
export interface OnboardingRunStateResult {
run: boolean
eligible: boolean
session_id?: string | null
run_id?: string | null
}
/** ``mark_profile_offered`` also latches ``onboarding.seen.profile_build_offered`` in the root config, so the first chat after onboarding gets the plain intro instead of the profile offer. */
export interface OnboardingSetRunParams {
run: boolean
mark_profile_offered?: boolean
}
/** ``rerun``: start a new onboarding chat even when one is in progress (Settings, Run onboarding again; it never claims the welcome trial). ``fresh_launch``: the app's once-per-launch start; a run the app was closed on does not count, so its chat is deleted and the run starts over. ``facts_source``: whether the backend runs on the user's own computer. ``locale``: the desktop's UI language, preferred over the backend OS locale. ``assume_fresh``: as on ``onboarding.state``. A new run on a first install claims the welcome trial before its chat exists; a failed claim is error 5079 and leaves no guest and no chat. A claim that is blocked (another install took the trial) with no trial or provider to run on is error 5080 and opens no chat. */
export interface OnboardingStartParams {
rerun?: boolean
fresh_launch?: boolean
assume_fresh?: boolean
facts_source?: OnboardingFactsSource
locale?: string | null
}
export type OnboardingFactsSource = 'local' | 'remote'
/** ``session_id`` is the runtime id the client attaches to; ``resumed`` is true when an onboarding chat already in progress was reopened instead of a new one started. ``run_id`` names the run in ``onboarding.ended``. */
export interface OnboardingStartResult {
session_id: string
stored_session_id: string
resumed: boolean
run_id: string
}
export interface OnboardingSkipParams {
session_id: string
profile?: string | null
}
export interface OnboardingSkipResult {
skipped: boolean
}
export interface VaultListResult {
items?: VaultItem[]
}
/** Metadata-only view (``VaultItemMeta.to_dict`` + ``backend``); never a secret. */
export interface VaultItem {
id: string
kind: string
label: string
origin?: string | null
created_at?: string
identifier?: string | null
identifier_type?: string | null
has_otp?: boolean | null
backend: string
}
export interface VaultSourcesResult {
sources?: VaultSource[]
}
export interface VaultSource {
name: string
display_name: string
enabled: boolean
needs_unlock: boolean
unlocked: boolean
installed: boolean
}
export interface VaultSourceSetParams {
profile?: string | null
name?: string | null
enabled?: boolean | null
}
export interface VaultSourceSetResult {
name: string
enabled: boolean
}
/** The master password is consumed by the manager CLI and never stored or logged. */
export interface VaultUnlockParams {
profile?: string | null
name?: string | null
password?: string | null
}
export interface VaultUnlockResult {
name: string
unlocked?: boolean
}
export interface VaultLockParams {
profile?: string | null
name?: string | null
}
export interface VaultLockResult {
locked?: boolean
}
/** ``secret`` goes straight into the encrypted store; the result carries only the new id. */
export interface VaultAddParams {
profile?: string | null
kind?: VaultKind | null
label?: string | null
origin?: string | null
secret?: Record<string, unknown> | null
}
export type VaultKind = 'login' | 'payment' | 'address'
export interface VaultAddResult {
id: string
}
export interface VaultRemoveParams {
profile?: string | null
id?: string | null
}
export interface VaultRemoveResult {
removed: boolean
}
export interface SessionForeignListParams {
profile?: string | null
source?: ForeignSource | null
offset?: number | null
limit?: number | null
}
export type ForeignSource = 'claude' | 'codex'
/** ``unreadable`` counts logs on this page that failed to parse. */
export interface SessionForeignListResult {
sessions?: ForeignSessionRow[]
next_offset?: number | null
host: string
unreadable?: number
}
/** ``hermes_cli/foreign_sessions_browser.py::list_foreign_sessions`` — ``id`` is an opaque handle, never a path. */
export interface ForeignSessionRow {
id: string
source: ForeignSource
label: string
title?: string
cwd?: string | null
mtime: number
turn_count?: number
excerpt?: string
}
export interface SessionForeignIdParams {
profile?: string | null
id?: string | null
}
/** Bounded to the last 40 turns / 8000 chars each; ``already_imported`` is the local id. */
export interface SessionForeignPreviewResult {
messages?: ForeignTurn[]
total?: number
truncated?: boolean
already_imported?: string | null
cwd?: string | null
}
export interface ForeignTurn {
role: string
content: string
}
export interface SessionForeignImportResult {
session_id: string
already_imported?: boolean
}
/** ``delegations``: recently failed async delegation tasks for the session (durable store), newest first. */
export interface SubagentListResult {
subagents?: SubagentSnapshot[]
delegations?: FailedDelegation[]
}
/** ``methods_subagents._SUBAGENT_SNAPSHOT_FIELDS`` projection of one live child record. */
export interface SubagentSnapshot {
subagent_id: string
parent_id?: string | null
depth?: number | null
goal?: string | null
delegation_id?: string | null
model?: string | null
started_at?: number | null
status?: SubagentStatus | null
tool_count?: number | null
last_tool?: string | null
accepting_steer?: boolean | null
}
/** Lifecycle of one delegated child (``tools/delegate_tool_child_run.py``); ``failed`` / ``error`` / ``timeout`` / ``interrupted`` / ``completed`` are terminal. */
export type SubagentStatus = 'queued' | 'running' | 'completed' | 'failed' | 'error' | 'timeout' | 'interrupted'
/** ``async_delegation.failed_delegations_for_session`` row: one failed task of an async delegation. */
export interface FailedDelegation {
delegation_id: string
task_index?: number
status: string
goal?: string
error?: string | null
dispatched_at?: number | null
completed_at?: number | null
}
export interface SubagentRosterResult {
sessions?: SubagentRosterEntry[]
}
export interface SubagentRosterEntry {
session_id: string
subagents?: number
background?: number
}
export interface SubagentIdParams {
session_id: string
profile?: string | null
subagent_id: string
}
export interface SubagentInterruptResult {
found: boolean
subagent_id: string
}
/** ``available`` is false while the child has no live transcript yet (or it was cleaned up). */
export interface SubagentTailResult {
subagent_id: string
available?: boolean
text?: string
truncated?: boolean
}
/** ``methods_projects._projects_payload``: every project (archived included) + the active id. */
export interface ProjectsPayload {
projects: ProjectInfo[]
active_id?: string | null
}
/** ``hermes_cli/projects_db.py::Project.to_dict`` — one stored project with its folders. */
export interface ProjectInfo {
id: string
slug: string
name: string
description?: string | null
icon?: string | null
color?: string | null
board_slug?: string | null
primary_path?: string | null
archived?: boolean
created_at: number
folders?: ProjectFolder[]
}
/** ``hermes_cli/projects_db.py::ProjectFolder.to_dict``. */
export interface ProjectFolder {
path: string
label?: string | null
is_primary?: boolean
added_at?: number | null
}
/** Any method addressed at one stored project (``5062`` when the id resolves to nothing). */
export interface ProjectIdParams {
profile?: string | null
id: string
}
export interface ProjectResult {
project: ProjectInfo
}
/** ``use`` also activates the new project. */
export interface ProjectsCreateParams {
profile?: string | null
name: string
folders?: string[] | null
slug?: string | null
primary_path?: string | null
description?: string | null
icon?: string | null
color?: string | null
board_slug?: string | null
use?: boolean
}
export interface OptionalProjectResult {
project?: ProjectInfo | null
}
/** Absent keys are left untouched; ``''`` clears ``color`` / ``icon``. */
export interface ProjectsUpdateParams {
profile?: string | null
id: string
name?: string | null
description?: string | null
icon?: string | null
color?: string | null
board_slug?: string | null
}
export interface ProjectsAddFolderParams {
profile?: string | null
id: string
path: string
label?: string | null
is_primary?: boolean
}
export interface ProjectFolderParams {
profile?: string | null
id: string
path: string
}
export interface ProjectsArchiveParams {
profile?: string | null
id: string
restore?: boolean
}
/** No ``id`` (or null) clears the active project. */
export interface ProjectsSetActiveParams {
profile?: string | null
id?: string | null
}
export interface ActiveIdResult {
active_id?: string | null
}
/** Absent ``cwd`` resolves the gateway's default completion cwd. */
export interface ProjectsForCwdParams {
profile?: string | null
cwd?: string | null
}
export interface ProjectsForCwdResult {
project?: ProjectInfo | null
cwd: string
branch?: string
}
/** ``scan`` asks the host to walk the policy roots itself (remote-gateway desktop). */
export interface ProjectsDiscoverReposParams {
profile?: string | null
scan?: boolean
}
export interface ProjectsDiscoverReposResult {
repos: DiscoveredRepo[]
discovery_policy?: RepoDiscoveryPolicy | null
}
/** ``methods_projects._discover_repos_payload`` row: a git root with session totals. */
export interface DiscoveredRepo {
root: string
label?: string
sessions?: number
last_active?: number
}
/** ``methods_projects._repo_discovery_policy`` — the effective ``desktop.repo_scan_*`` config. */
export interface RepoDiscoveryPolicy {
enabled: boolean
roots: string[]
exclude_paths: string[]
}
/** Repos as ``{root, label}`` objects or bare root strings; entries without a root are skipped. */
export interface ProjectsRecordReposParams {
profile?: string | null
repos?: (RecordRepoItem | string)[] | null
discovery_policy?: RepoDiscoveryPolicyParams | null
}
export interface RecordRepoItem {
root: string
label?: string | null
}
/** The policy the desktop scanned under (short or ``repo_scan_*`` long keys both accepted). */
export interface RepoDiscoveryPolicyParams {
enabled?: boolean | null
roots?: string[] | null
exclude_paths?: string[] | null
repo_scan_enabled?: boolean | null
repo_scan_roots?: string[] | null
repo_scan_exclude_paths?: string[] | null
}
export interface ProjectsRecordReposResult {
repos: DiscoveredRepo[]
discovery_policy?: RepoDiscoveryPolicy | null
accepted: boolean
}
export interface ProjectsTreeParams {
profile?: string | null
preview_limit?: number | null
session_limit?: number | null
}
export interface ProjectsTreeResult {
projects: ProjectTreeNode[]
active_id?: string | null
scoped_session_ids?: string[]
}
/** ``project_tree._project_node`` — explicit, auto (git root) or the synthetic Home bucket. */
export interface ProjectTreeNode {
id: string
label: string
path?: string | null
color?: string | null
icon?: string | null
isAuto?: boolean
isNoProject?: boolean
sessionCount?: number
lastActive?: number
totalTokens?: number
totalCostUsd?: number
repos?: ProjectTreeRepo[]
previewSessions?: ProjectTreeSession[]
sessionIds?: string[]
}
export interface ProjectTreeRepo {
id: string
label: string
path?: string | null
groups?: ProjectTreeLane[]
sessionCount?: number
}
/** One branch / worktree / kanban lane inside a repo; ``sessions`` is empty unless hydrated. */
export interface ProjectTreeLane {
id: string
label: string
path?: string | null
isMain?: boolean
isKanban?: boolean
isGit?: boolean
sessions?: ProjectTreeSession[]
}
/** ``methods_projects._project_tree_row`` + ``project_tree.stamp_profile``: the minimal row the sidebar renders, stamped with the profile it belongs to. */
export interface ProjectTreeSession {
id: string
title?: string | null
preview?: string | null
source?: string | null
model?: string | null
started_at?: number | null
ended_at?: number | null
last_active?: number | null
message_count?: number
tool_call_count?: number
input_tokens?: number
output_tokens?: number
is_active?: boolean
cwd?: string | null
git_branch?: string | null
git_repo_root?: string | null
parent_session_id?: string | null
pinned?: boolean | null
unread?: boolean | null
archived?: boolean | null
actual_cost_usd?: number | null
estimated_cost_usd?: number | null
handoff_platform?: string | null
handoff_state?: string | null
_lineage_root_id?: string | null
_lineage_ids?: string[] | null
continuation_kind?: string | null
profile?: string | null
[key: string]: unknown
}
export interface ProjectsProjectSessionsParams {
profile?: string | null
project_id: string
session_limit?: number | null
}
export interface ProjectsProjectSessionsResult {
project?: ProjectTreeNode | null
}
/** ``knownRevision``: the spritesheet revision the caller already holds (send-once bytes). */
export interface PetInfoParams {
profile?: string | null
knownRevision?: string | null
}
/** ``server._pet_sprite_payload`` behind ``enabled``; every sprite field is absent when the pet display is off, ``spritesheetBase64`` is elided when ``spritesheetUnchanged``. */
export interface PetInfoResult {
enabled: boolean
slug?: string | null
displayName?: string | null
mime?: string | null
spritesheetBase64?: string | null
spritesheetRevision?: string | null
spritesheetUnchanged?: boolean | null
frameW?: number | null
frameH?: number | null
framesPerState?: number | null
framesByState?: Record<string, number> | null
framesByRow?: Record<string, number> | null
loopMs?: number | null
scale?: number | null
stateRows?: string[] | null
[key: string]: unknown
}
export interface PetInfoMetaResult {
enabled: boolean
slug?: string | null
displayName?: string | null
scale?: number | null
spritesheetRevision?: string | null
}
/** ``graphics`` opts into the kitty payload when the TTY speaks it; ``cols`` overrides the width. */
export interface PetCellsParams {
profile?: string | null
state?: string | null
cols?: number | null
graphics?: boolean
}
/** Unicode: ``frames`` is frame → row → cell ``[tr,tg,tb,ta, br,bg,bb,ba]``; kitty (``graphics`` set): ``frames`` are transmit escapes and ``placeholder`` the text grid. */
export interface PetCellsResult {
enabled: boolean
slug?: string | null
displayName?: string | null
state?: string | null
cols?: number | null
frameMs?: number | null
frames?: number[][][][] | string[] | null
scale?: number | null
graphics?: string | null
imageId?: number | null
color?: string | null
rows?: number | null
placeholder?: string[] | null
}
export interface PetGalleryParams {
profile?: string | null
localOnly?: boolean
}
export interface PetGalleryResult {
enabled: boolean
active?: string
pets?: PetGalleryEntry[]
}
export interface PetGalleryEntry {
slug: string
displayName: string
installed: boolean
spritesheetUrl?: string
curated?: boolean | null
generated?: boolean
}
export interface PetSlugParams {
profile?: string | null
slug: string
}
export interface PetSlugResult {
ok: boolean
slug: string
displayName?: string | null
}
export interface PetRenameParams {
profile?: string | null
slug: string
name: string
}
export interface PetExportResult {
ok: boolean
filename: string
zipBase64: string
}
/** ``url``: spritesheet source for a not-yet-installed pet. */
export interface PetThumbParams {
profile?: string | null
slug: string
url?: string | null
}
export interface PetThumbResult {
ok: boolean
slug: string
dataUri?: string | null
}
export interface PetScaleParams {
profile?: string | null
scale?: unknown
}
export interface PetScaleResult {
ok: boolean
scale: number
}
/** ``text`` is normally a string; the relay / hosted paths may hand a structured (parts list) payload, and the busy path renders it. Truncation (rewind / edit / regenerate) needs explicit consent: ``confirm_truncate`` plus one durable target (``truncate_before_row_id`` preferred, ``truncate_before_message_id``, or the legacy ``truncate_before_user_ordinal``). */
export interface PromptSubmitParams {
session_id: string
profile?: string | null
text?: unknown
display_kind?: string | null
interrupted?: boolean | null
queued?: boolean | null
surface?: string | null
voice_context?: string | null
voice_turn?: boolean | null
title_preview?: string | null
truncate_before_user_ordinal?: number | null
truncate_before_row_id?: number | null
truncate_before_message_id?: string | null
confirm_truncate?: boolean | null
confirm_empty_truncate?: boolean | null
confirm_deep_truncate?: boolean | null
rebind_survivor_row_ids?: number[] | null
}
/** ``status`` is absent only on the typed-stop-phrase reply (``voice_stopped``). After a truncation the survivor row ids let the client rebind its cached ``rowId``s (``None`` map entries: drop the cached id). ``turn_isolation`` marks a compute-host dispatch. */
export interface PromptSubmitResult {
status?: PromptSubmitStatus | null
voice_stopped?: boolean | null
user_row_id?: number | null
survivor_user_row_ids?: (number | null)[] | null
survivor_row_id_map?: Record<string, number | null> | null
turn_isolation?: boolean | null
admission_id?: string | null
forwarded?: boolean | null
}
export type PromptSubmitStatus = 'streaming' | 'queued' | 'steered' | 'redirected'
export interface ClipboardPasteParams {
session_id: string
profile?: string | null
}
/** ``methods_prompt.py::_attached_image_result``: the image is queued for the next turn. */
export interface AttachedImageResult {
name?: string | null
width?: number | null
height?: number | null
token_estimate?: number | null
attached: boolean
path?: string | null
count?: number | null
remainder?: string | null
text?: string | null
bytes?: number | null
message?: string | null
}
export interface ImageAttachParams {
session_id: string
profile?: string | null
path: string
}
/** ``content_base64`` (or the ``data`` alias) carries the bytes; ``filename`` / ``ext`` only hint the extension — magic bytes decide. */
export interface ImageAttachBytesParams {
session_id: string
profile?: string | null
content_base64?: string | null
data?: string | null
filename?: string | null
ext?: string | null
}
/** Host ``path`` or base64 ``content_base64`` / ``data``; ``first_page`` / ``last_page`` bound the render (per-call page cap enforced server-side). */
export interface PdfAttachParams {
session_id: string
profile?: string | null
path?: string | null
content_base64?: string | null
data?: string | null
filename?: string | null
first_page?: number | null
last_page?: number | null
}
export interface PdfAttachResult {
attached: boolean
filename: string
pages_attached: number
pages: PdfPage[]
count: number
text: string
}
export interface PdfPage {
name?: string | null
width?: number | null
height?: number | null
token_estimate?: number | null
path: string
page: number
}
/** ``path`` when the file is gateway-visible, else ``data_url`` carries the bytes; ``name`` labels an uploaded file. */
export interface FileAttachParams {
session_id: string
profile?: string | null
path?: string | null
data_url?: string | null
name?: string | null
staged_upload?: StagedFileUpload | null
}
/** Source identity returned by the browser upload route, checked against the live profile. */
export interface StagedFileUpload {
install_id: string
path: string
profile_home: string
}
export interface FileAttachResult {
attached: boolean
name: string
path: string
ref_path: string
ref_text: string
uploaded: boolean
}
export interface ImageDetachParams {
session_id: string
profile?: string | null
path: string
}
export interface ImageDetachResult {
detached: boolean
count: number
}
export interface InputDetectDropParams {
session_id: string
profile?: string | null
text?: string | null
}
/** ``matched: false`` alone when the text is not a drop; an image drop is queued immediately (``is_image`` + ``count``), a file drop only yields the ``text`` to insert. */
export interface InputDetectDropResult {
name?: string | null
width?: number | null
height?: number | null
token_estimate?: number | null
matched: boolean
is_image?: boolean | null
path?: string | null
count?: number | null
text?: string | null
}
export interface SideAgentParams {
session_id: string
profile?: string | null
text: string
}
/** The side agent runs detached; its answer lands on the parent session as an event carrying this ``task_id``. */
export interface TaskIdResult {
task_id: string
}
export interface PreviewRestartParams {
session_id: string
profile?: string | null
url: string
cwd?: string | null
context?: string | null
}
export interface ClarifyLockParams {
request_id: string
question_id: string
answer?: unknown
profile?: string | null
}
/** ``remaining`` lists the qids still unanswered; the lock that empties it resolves the request. ``expired``: the wait already ended (timeout / cancel) — not an error. */
export interface ClarifyLockResult {
status: ClarifyLockStatus
remaining?: string[] | null
}
export type ClarifyLockStatus = 'ok' | 'expired'
export interface RequestAnswerParams {
id: string
result: Record<string, unknown>
profile?: string | null
}
export interface RequestAnswerResult {
status: ClarifyLockStatus
}
export interface ApprovalPendingParams {
session_id: string
profile?: string | null
}
export interface ApprovalPendingResult {
approvals: PendingApproval[]
}
/** One unresolved ``tools/approval.py`` gateway queue entry as ``server._approval_request_payload`` renders it (command redacted; ``choices`` precomputed). The key set is owned by the approval tool. */
export interface PendingApproval {
request_id?: string | null
command?: string | null
description?: string | null
pattern_key?: string | null
pattern_keys?: string[] | null
allow_permanent?: boolean | null
allow_session?: boolean | null
smart_denied?: boolean | null
choices?: string[] | null
tool_name?: string | null
[key: string]: unknown
}
export interface ApprovalReceivedParams {
session_id: string
profile?: string | null
request_id: string
}
export interface ApprovalReceivedResult {
acknowledged: boolean
}
/** ``choice`` is one of the offered ``approval`` choices (once / session / always / deny); ``all`` resolves every pending approval, ``request_id`` a specific one, neither the oldest. */
export interface ApprovalRespondParams {
session_id: string
profile?: string | null
choice?: string | null
all?: boolean | null
request_id?: string | null
}
export interface ApprovalRespondResult {
resolved: number
}
export interface VoiceToggleParams {
action?: VoiceToggleAction
profile?: string | null
}
export type VoiceToggleAction = 'status' | 'on' | 'off' | 'tts'
/** ``methods_voice.py::_voice_status_payload`` (+ the requirements probe on ``status``, the spoken stop hint on ``on``). */
export interface VoiceToggleResult {
enabled: boolean
record_key: string
tts: boolean
stop_hint?: string | null
available?: boolean | null
audio_available?: boolean | null
stt_available?: boolean | null
details?: string | null
}
export interface VoiceRecordParams {
action?: VoiceRecordAction
session_id?: string | null
profile?: string | null
}
export type VoiceRecordAction = 'start' | 'stop'
export interface VoiceRecordResult {
status: VoiceRecordStatus
reason?: string | null
}
export type VoiceRecordStatus = 'recording' | 'stopped' | 'busy'
export interface VoiceTtsParams {
text: string
profile?: string | null
}
export interface VoiceTtsResult {
status: string
}
/** ``surface`` names the caller ("tui" | "gui"); ``persist`` is the explicit gesture that also flips ``wake_word.enabled`` on; ``client_capture`` asks for PCM streamed via wake.feed. */
export interface WakeStartParams {
surface?: string | null
persist?: boolean | null
client_capture?: boolean | null
session_id?: string | null
profile?: string | null
}
/** ``started: false`` carries ``reason`` (unavailable / disabled / disabled_for_surface / owned); ``sample_rate`` / ``frame_length`` describe the PCM frames the armed detector expects. */
export interface WakeStartResult {
started: boolean
reason?: string | null
hint?: string | null
phrase?: string | null
provider?: string | null
owner_surface?: string | null
enabled_persisted?: boolean | null
capture?: string | null
sample_rate?: number | null
frame_length?: number | null
}
export interface WakeStopParams {
persist?: boolean | null
profile?: string | null
}
export interface WakeStopResult {
reason?: string | null
stopped: boolean
disabled_persisted: boolean
}
export interface WakeControlParams {
profile?: string | null
}
export interface WakePauseResult {
reason?: string | null
paused: boolean
}
export interface WakeResumeResult {
reason?: string | null
resumed: boolean
}
export interface WakeStatusParams {
surface?: string | null
client_capture?: boolean | null
profile?: string | null
}
/** ``enabled`` is config truth; ``listening`` is this caller's armed detector; ``audio_silent`` means armed but deaf (see ``hint``). */
export interface WakeStatusResult {
listening: boolean
owned_by_caller: boolean
owner_surface?: string | null
phrase: string
provider: string
configured_surface: string
input_device: WakeInputDevice
available: boolean
hint: string
enabled: boolean
audio_silent: boolean
capture: string
local_input_available: boolean
sample_rate: number
frame_length: number
}
/** ``tools/wake_word.py::_describe_input_device`` — PortAudio diagnostics for the configured mic. */
export interface WakeInputDevice {
selector?: number | string | null
name?: string | null
error?: string | null
max_input_channels?: number | null
default_samplerate?: number | null
hostapi_index?: number | null
hostapi?: string | null
[key: string]: unknown
}
/** ``pcm`` (or the ``pcm_b64`` alias): base64 int16 mono little-endian, 16 kHz only. */
export interface WakeFeedParams {
pcm?: string | null
pcm_b64?: string | null
sample_rate?: number | null
profile?: string | null
}
export interface WakeFeedResult {
reason?: string | null
fed: boolean
}
export interface SessionCreateParams {
profile?: string | null
cols?: number | null
source?: string | null
cwd?: string | null
cwd_explicit?: boolean | null
messages?: SeedMessage[] | null
parent_session_id?: string | null
title?: string | null
model?: string | null
provider?: string | null
reasoning_effort?: string | null
fast?: boolean | null
service_tier?: string | null
close_on_disconnect?: boolean
hidden?: boolean
room_plumbing?: boolean
follow_profile_config?: boolean
idempotency_key?: string | null
}
/** One create-time transcript row (``session_history._coerce_seed_history``); ``text`` is the legacy alias of ``content``; only ``display_kind: "hidden"`` is accepted from the wire. Clients forward stored rows verbatim (``_row_id``, ``timestamp``, …) and the coercer drops what it does not use, so the row stays open. */
export interface SeedMessage {
role: string
content?: string | null
text?: string | null
display_kind?: string | null
[key: string]: unknown
}
export interface SessionCreateResult {
session_id: string
stored_session_id: string
message_count: number
messages: TranscriptMessage[]
info: SessionLiveInfo
}
/** One transcript row as the gateway PROJECTS it for renderers (``session_history._project_history``): ``text``, display-only ``timestamp`` / ``display_kind`` / ``display_metadata``, the durable ``row_id`` rewind targets, and for tool rows raw ``content``, ``tool_call_id``, ``name``, ``context`` and ``args``. Assistant detail sidecars (``reasoning``, …) ride as extra keys. */
export interface TranscriptMessage {
role: string
text?: string | null
content?: unknown | null
tool_call_id?: string | null
timestamp?: number | null
row_id?: number | null
display_kind?: string | null
display_metadata?: unknown | null
name?: string | null
context?: string | null
args?: Record<string, unknown> | null
labels?: ToolLabel[] | null
reasoning?: string | null
[key: string]: unknown
}
/** ``tools.tool_labels.ToolLabel`` — what one call executed through the tool_search bridge is, in words. Clients render ``text`` (or ``app``/``action`` in their own columns) and never parse the tool name themselves. */
export interface ToolLabel {
kind: ToolLabelKind
app: string
action: string
emoji: string
text: string
name: string
preview?: string
}
/** Which surface one inner call of a bridged ``tool_call`` runs on. */
export type ToolLabelKind = 'connector' | 'mcp' | 'tool'
export interface SessionBranchStoredParams {
profile?: string | null
parent_session_id: string
cols?: number | null
source?: string | null
cwd?: string | null
idempotency_key?: string | null
}
export interface SessionBranchStoredResult {
session_id: string
stored_session_id: string
message_count: number
messages_omitted: boolean
info: SessionLiveInfo
}
/** ``session_id`` is the STORED id (or an exact title); the reply's ``session_id`` is the runtime id. */
export interface SessionResumeParams {
session_id: string
profile?: string | null
cols?: number | null
source?: string | null
lazy?: boolean
defer_history?: boolean
omit_messages?: boolean
eager_build?: boolean
close_on_disconnect?: boolean
inline_images?: boolean
}
export interface SessionResumeResult {
session_id: string
message_count: number
messages: TranscriptMessage[]
info: SessionLiveInfo
stored_session_id?: string | null
resumed?: string | null
session_key?: string | null
messages_omitted?: boolean | null
hydrating?: boolean | null
running?: boolean | null
turn_started_at?: number | null
started_at?: number | null
status?: string | null
inflight?: InflightTurn | null
queued?: QueuedPrompt | null
pending_approval?: PendingApproval | null
open_requests?: OpenRequestEntry[] | null
pending_connection?: ConnectionRequestPayload | null
todo_state?: TodoState | null
auto_continue?: AutoContinue | null
}
/** ``session_auto_continue._inflight_snapshot``: the live (or retained failed) turn a reconnecting client rebuilds its bubbles from. */
export interface InflightTurn {
assistant?: string
streaming?: boolean
user?: string
display_kind?: string | null
display_metadata?: Record<string, unknown> | null
corrections?: string[] | null
correction_offsets?: number[] | null
error?: string | null
status?: string | null
recoverable?: boolean | null
error_surface?: Record<string, unknown> | null
}
export interface QueuedPrompt {
user: string
}
/** One unanswered server→client request (``server_requests.Request.snapshot``); the reconnecting client re-delivers it to its request handlers. */
export interface OpenRequestEntry {
id: string
method: string
params: Record<string, unknown>
}
/** ``ConnectionOperation.request_payload``: opens the card; also the ``pending_connection`` resume snapshot so a client that missed the event restores the card with the server's deadline. */
export interface ConnectionRequestPayload {
op_id: string
seq: number
deadline_at: number
timeout_seconds: number
targets: ConnectionOperationTarget[]
tool_call_id?: string | null
display?: ConnectionDisplay | null
}
/** ``manage_connections`` action ``display``: the directory card, with these slugs pinned as Suggested. */
export interface ConnectionDisplay {
suggested: string[]
}
/** ``tool_progress._normalize_todo_state``: the authoritative todo snapshot. */
export interface TodoState {
todos: Record<string, unknown>[]
revision: number
}
/** A crash-interrupted turn was scheduled to continue right after this resume. */
export interface AutoContinue {
attempt: number
interrupted_at: number
}
export interface SessionActivateParams {
session_id: string
profile?: string | null
cols?: number | null
omit_messages?: boolean
}
export interface SessionActivateResult {
session_id: string
message_count: number
messages: TranscriptMessage[]
info: SessionLiveInfo
stored_session_id?: string | null
resumed?: string | null
session_key?: string | null
messages_omitted?: boolean | null
hydrating?: boolean | null
running?: boolean | null
turn_started_at?: number | null
started_at?: number | null
status?: string | null
inflight?: InflightTurn | null
queued?: QueuedPrompt | null
pending_approval?: PendingApproval | null
open_requests?: OpenRequestEntry[] | null
pending_connection?: ConnectionRequestPayload | null
todo_state?: TodoState | null
auto_continue?: AutoContinue | null
}
export interface SessionListParams {
profile?: string | null
title?: string | null
limit?: number | null
include_hidden?: boolean
}
export interface SessionListResult {
sessions: SessionListRow[]
}
/** ``methods_session._session_row_summary``; ``resolved_id`` only on a title lookup that followed a compression lineage to its tip. */
export interface SessionListRow {
id: string
resolved_id?: string | null
title?: string
preview?: string
started_at?: number
message_count?: number
live_message_count?: number | null
source?: string
_lineage_root_id?: string | null
}
export interface SessionMostRecentParams {
profile?: string | null
}
export interface SessionMostRecentResult {
session_id: string | null
title?: string | null
started_at?: number | null
source?: string | null
}
export interface SessionActiveListParams {
profile?: string | null
current_session_id?: string | null
}
export interface SessionActiveListResult {
sessions: SessionActiveItem[]
}
/** ``server._session_live_item``. */
export interface SessionActiveItem {
current: boolean
id: string
last_active: number
message_count: number
model: string
preview: string
session_key: string
source?: string | null
started_at: number
status: LiveSessionStatus
title: string
}
export type LiveSessionStatus = 'idle' | 'starting' | 'waiting' | 'working' | 'streaming' | 'resuming'
/** ``session_id`` is the STORED id. */
export interface SessionDeleteParams {
session_id: string
profile?: string | null
}
export interface SessionDeleteResult {
deleted: string
}
export interface SessionTitleParams {
session_id: string
profile?: string | null
title?: string | null
}
export interface SessionTitleResult {
title: string
session_key?: string | null
pending?: boolean | null
}
/** ``session_id`` is a live runtime id first, else a stored id / key / title. */
export interface SessionSetHiddenParams {
session_id: string
hidden: boolean
profile?: string | null
}
export interface SessionSetHiddenResult {
hidden: boolean
session_key: string
}
/** ``session_id`` (or its ``session_key`` alias) is a live runtime id first, else a stored id / key / title. */
export interface SessionArchiveParams {
session_id?: string | null
session_key?: string | null
archived?: boolean
profile?: string | null
}
export interface SessionArchiveResult {
archived: boolean
session_key: string
}
export interface SessionWorkspaceMoveParams {
profile?: string | null
session_key: string
cwd: string
}
export interface SessionWorkspaceMoveResult {
cwd: string
branch?: string | null
git_repo_root?: string | null
}
export interface SessionCwdSetParams {
session_id: string
profile?: string | null
cwd: string
}
/** The refreshed ``session.info`` view (full agent view, or the lazy shape). */
export interface SessionCwdSetResult {
model?: string
provider?: string
reasoning_effort?: string
reasoning_effort_wire?: string
service_tier?: string
fast?: boolean
yolo?: boolean
approval_mode?: string
tools?: Record<string, string[]>
skills?: Record<string, string[]>
cwd?: string
branch?: string | null
project?: ProjectRef | null
terminal_backend?: string
personality?: string
running?: boolean
turn_started_at?: number | null
title?: string
stored_session_id?: string
desktop_contract?: number | string | null
version?: string
release_date?: string
update_behind?: unknown | null
update_command?: string
usage?: Usage | null
profile_name?: string | null
mcp_servers?: McpServerStatus[]
system_prompt?: string | null
credential_warning?: string | null
lazy?: boolean | null
[key: string]: unknown
}
export interface SessionCloseParams {
session_id: string
profile?: string | null
}
export interface SessionCloseResult {
closed: boolean
messages?: string[]
}
export interface SessionBranchParams {
session_id: string
profile?: string | null
name?: string | null
count?: number | null
idempotency_key?: string | null
}
export interface SessionBranchResult {
session_id: string
stored_session_id: string
title: string
parent: string
message_count: number
messages: TranscriptMessage[]
info: SessionLiveInfo
}
export interface SessionBranchWholeParams {
session_id: string
profile?: string | null
name?: string | null
idempotency_key?: string | null
}
export interface SessionBranchWholeResult {
session_id: string
stored_session_id: string
title: string
parent: string
message_count: number
messages_omitted: boolean
info: SessionLiveInfo
}
export interface SessionUndoParams {
session_id: string
profile?: string | null
intent?: UndoIntent | null
}
export type UndoIntent = 'retry' | 'undo'
export interface SessionUndoResult {
removed: number
}
export interface SessionSaveParams {
session_id: string
profile?: string | null
}
/** Under turn isolation the compute host's result passes through verbatim. */
export interface SessionSaveResult {
file?: string | null
[key: string]: unknown
}
export interface SessionStatusParams {
session_id: string
profile?: string | null
}
export interface SessionStatusResult {
output: string
}
export interface SessionHistoryParams {
session_id: string
profile?: string | null
}
export interface SessionHistoryResult {
count: number
messages: TranscriptMessage[]
}
export interface SessionUsageParams {
session_id: string
profile?: string | null
}
export interface SessionUsageResult {
model?: string
input?: number
output?: number
reasoning?: number
prompt?: number
completion?: number
total?: number
calls?: number
compressions?: number | null
context_used?: number | null
context_max?: number | null
context_percent?: number | null
context_source?: string | null
context_estimated?: boolean | null
cache_hit_pct?: number | null
cache_read?: number | null
cache_write?: number | null
avg_latency_s?: number | null
avg_tps?: number | null
active_subagents?: number | null
dev_credits_spent_micros?: number | null
cost_usd?: number | null
cost_status?: string | null
plan_gauge?: PlanGauge | null
credits_lines?: string[] | null
credits_usage_window?: boolean | null
[key: string]: unknown
}
export interface SessionContextBreakdownParams {
session_id: string
profile?: string | null
}
/** ``agent.context_breakdown.compute_session_context_breakdown`` (empty categories before the agent builds) plus the per-file context manifest (empty until the agent exists). */
export interface SessionContextBreakdownResult {
categories: ContextCategory[]
context_max: number
context_percent: number
context_used: number
estimated_total: number
context_estimated: boolean
context_source: string
model: string
context_files?: ContextFileSource[]
}
export interface ContextCategory {
color: string
id: string
label: string
tokens: number
}
/** One row of ``agent.context_file_sources.list_context_file_sources``. */
export interface ContextFileSource {
label: string
path: string
chars: number
est_tokens: number
loaded: boolean
status: string
}
export interface SessionCompressParams {
session_id: string
profile?: string | null
focus_topic?: string | null
}
/** In-process: the before/after summary + replacement transcript. Compute host: its result passes through (hence open) with ``turn_isolation``; a lock held elsewhere answers ``compressed: false``. */
export interface SessionCompressResult {
status?: string | null
removed?: number | null
before_messages?: number | null
after_messages?: number | null
before_tokens?: number | null
after_tokens?: number | null
summary?: CompressionSummary | null
usage?: Usage | null
info?: SessionLiveInfo | null
messages?: TranscriptMessage[] | null
compressed?: boolean | null
lock_held?: boolean | null
message?: string | null
turn_isolation?: boolean | null
host_ack?: Record<string, unknown> | null
[key: string]: unknown
}
/** ``agent.manual_compression_feedback.summarize_manual_compression``. */
export interface CompressionSummary {
noop?: boolean
aborted?: boolean
refused_would_grow?: boolean | null
fallback_used?: boolean | null
headline?: string
token_line?: string
note?: string | null
[key: string]: unknown
}
export interface SessionInterruptParams {
session_id: string
profile?: string | null
expected_hosted_task_id?: string | null
}
export interface SessionInterruptResult {
status: InterruptStatus
interrupted?: boolean | null
turn_isolation?: boolean | null
}
export type InterruptStatus = 'interrupted' | 'not_interrupted'
export interface SessionCorrectionParams {
session_id: string
profile?: string | null
text: string
}
export interface SessionCorrectionResult {
status: CorrectionStatus
text: string
}
export type CorrectionStatus = 'queued' | 'redirected' | 'rejected'
export interface SpawnTreeSaveParams {
profile?: string | null
subagents: Record<string, unknown>[]
session_id?: string | null
started_at?: number | null
finished_at?: number | null
label?: string | null
}
export interface SpawnTreeSaveResult {
path: string
session_id: string
}
export interface SpawnTreeListParams {
profile?: string | null
session_id?: string | null
cross_session?: boolean
limit?: number | null
}
export interface SpawnTreeListResult {
entries: SpawnTreeEntry[]
}
/** Index row (``server._append_spawn_tree_index``) or a legacy file scan. */
export interface SpawnTreeEntry {
path: string
session_id?: string | null
started_at?: number | null
finished_at?: number | null
label?: string
count?: number
[key: string]: unknown
}
export interface SpawnTreeLoadParams {
profile?: string | null
path: string
}
/** The snapshot file as written by ``spawn_tree.save`` (open: the file is the contract). */
export interface SpawnTreeLoadResult {
session_id?: string | null
started_at?: number | null
finished_at?: number | null
label?: string | null
subagents?: Record<string, unknown>[]
[key: string]: unknown
}
export interface TerminalResizeParams {
session_id: string
profile?: string | null
cols?: number | null
}
export interface TerminalResizeResult {
cols: number
}
export interface SessionEventsSinceParams {
session_id: string
profile?: string | null
last_seen?: number | null
replay_epoch?: string | null
}
export interface SessionEventsSinceResult {
events: Record<string, unknown>[]
latest_seq: number
truncated: boolean
count: number
epoch: string
open_requests: OpenRequestEntry[]
}
export interface SessionEventsStatsParams {
profile?: string | null
}
/** ``event_replay.replay_stats``. */
export interface SessionEventsStatsResult {
sessions: number
events: number
bytes: number
max_per_session: number
max_bytes_per_session: number
max_bytes_process: number
}
/** Needs a ``template`` or ``instructions`` / ``input``; a live ``session_id`` lends its model. */
export interface LlmOneshotParams {
profile?: string | null
template?: string | null
instructions?: string | null
input?: string | null
variables?: Record<string, unknown> | null
task?: string | null
temperature?: number | null
max_tokens?: number | null
session_id?: string | null
}
export interface LlmOneshotResult {
text: string
}
export interface SystemBatteryParams {
profile?: string | null
}
export interface SystemBatteryResult {
available: boolean
percent?: number | null
plugged?: boolean | null
category?: BatteryCategory
}
/** ``agent/battery.py::battery_category`` colour bucket. */
export type BatteryCategory = 'good' | 'warn' | 'bad' | 'critical' | 'dim'
export interface ProcessStopParams {
session_id?: string | null
profile?: string | null
}
export interface ProcessStopResult {
killed: number
delegations?: number
}
export interface AgentsListParams {
profile?: string | null
}
export interface AgentsListResult {
processes?: AgentProcessRow[]
}
export interface AgentProcessRow {
session_id: string
command: string
status: string
uptime: number
}
export interface ProcessListParams {
session_id: string
profile?: string | null
}
export interface ProcessListResult {
processes?: ProcessEntry[]
}
/** ``tools/process_registry.py::list_sessions`` row plus the gateway's ``output_tail``. */
export interface ProcessEntry {
session_id: string
command?: string
cwd?: string | null
pid?: number | null
owner_task_id?: string | null
started_at?: string | null
uptime_seconds?: number | null
status?: string
output_preview?: string
output_tail?: string | null
session_scoped?: boolean | null
watch_patterns?: string[] | null
watch_hit?: boolean | null
notify_on_complete?: boolean | null
exit_code?: number | null
exited_at?: number | null
started_epoch?: number | null
completion_reason?: string | null
detached?: boolean | null
[key: string]: unknown
}
export interface ProcessKillParams {
session_id: string
process_id: string
profile?: string | null
}
/** ``tools/process_registry.py::kill_process`` snapshot; ``error`` rides on the failure statuses. */
export interface ProcessKillResult {
status: ProcessKillStatus
session_id?: string | null
command?: string | null
exit_code?: number | null
completion_reason?: string | null
termination_source?: string | null
output?: string | null
error?: string | null
[key: string]: unknown
}
export type ProcessKillStatus = 'killed' | 'already_exited' | 'not_found' | 'error'
export interface ShellExecParams {
command: string
profile?: string | null
}
export interface ShellExecResult {
stdout: string
stderr: string
code: number
}
export interface CliExecParams {
argv: string[]
timeout?: number | null
profile?: string | null
}
export interface CliExecResult {
blocked: boolean
code: number
output: string
hint?: string | null
}
export interface CommandsCatalogParams {
session_id?: string | null
profile?: string | null
}
export interface CommandsCatalogResult {
pairs?: string[][]
sub?: Record<string, string[]>
canon?: Record<string, string>
commands?: Record<string, CommandCatalogMeta>
categories?: CommandCategory[]
skills?: Record<string, SkillCatalogEntry>
skill_count?: number
warning?: string
plugin_discovery_error?: string
plugin_commands?: Record<string, string>
}
export interface CommandCatalogMeta {
argument_mode?: ArgumentMode | null
desktop?: string | null
desktop_subcommands?: string[] | null
}
export type ArgumentMode = 'options' | 'text' | 'mixed'
export interface CommandCategory {
name: string
pairs?: string[][]
}
export interface SkillCatalogEntry {
usage?: number
origin?: string
}
export interface CommandResolveParams {
name?: string | null
profile?: string | null
}
export interface CommandResolveResult {
canonical: string
description: string
category: string
}
export interface CommandDispatchParams {
name: string
arg?: string | null
session_id?: string | null
profile?: string | null
}
/** One structured directive: ``exec``/``plugin`` carry ``output``; ``alias`` a ``target``; ``send``/``prefill``/``skill`` a ``message`` (UIs render ``display``, never ``message``). */
export interface CommandDispatchResult {
type: DispatchType
output?: string | null
target?: string | null
message?: string | null
notice?: string | null
display?: string | null
name?: string | null
status?: string | null
}
/** ``apps/shared/src/slash.ts::parseCommandDispatch`` branches on this. */
export type DispatchType = 'exec' | 'alias' | 'plugin' | 'send' | 'skill' | 'prefill'
export interface SlashExecParams {
session_id: string
command: string
profile?: string | null
}
/** Plain worker/plugin text in ``output`` (+ ``warning``), or — when the command was rerouted to ``command.dispatch`` — that method's directive fields with ``type`` set. */
export interface SlashExecResult {
output?: string | null
warning?: string | null
type?: DispatchType | null
target?: string | null
message?: string | null
notice?: string | null
display?: string | null
name?: string | null
status?: string | null
}
export interface InsightsGetParams {
days?: number | null
profile?: string | null
}
export interface InsightsGetResult {
days: number
sessions: number
messages: number
}
export interface ConfigShowParams {
profile?: string | null
}
export interface ConfigShowResult {
sections?: ConfigSection[]
[key: string]: unknown
}
export interface ConfigSection {
title: string
rows?: string[][]
}
export interface RollbackListParams {
session_id: string
profile?: string | null
}
export interface RollbackListResult {
enabled: boolean
checkpoints?: RollbackCheckpoint[]
}
export interface RollbackCheckpoint {
hash?: string
timestamp?: string
message?: string
}
export interface RollbackRestoreParams {
session_id: string
hash: string
file_path?: string | null
profile?: string | null
all?: boolean | null
}
/** ``tools/checkpoint_manager.py::restore`` outcome; ``history_removed`` is added for a full (non-file) restore that also rewound the live transcript. */
export interface RollbackRestoreResult {
success: boolean
restored_to?: string | null
reason?: string | null
directory?: string | null
file?: string | null
restored_files?: string[] | null
skipped_user_edits?: string[] | null
skipped_oversize?: string[] | null
failed_deletes?: string[] | null
history_removed?: number | null
error?: string | null
debug?: unknown | null
[key: string]: unknown
}
export interface RollbackDiffParams {
session_id: string
hash: string
profile?: string | null
}
export interface RollbackDiffResult {
stat?: string
diff?: string
rendered?: string | null
}
export interface CronManageParams {
action?: CronAction
name?: string | null
include_disabled?: boolean | string | null
schedule?: string | null
prompt?: string | null
repeat?: number | string | null
continuity?: boolean | string | null
deliver?: string | null
profile?: string | null
}
export type CronAction = 'list' | 'add' | 'remove' | 'pause' | 'resume'
/** Pass-through of ``tools/cronjob_tools.py::cronjob`` JSON: ``list`` → ``jobs``/``count`` (+ ``scoped`` when profile-scoped); ``add`` → the created job's summary + ``job``; ``remove`` → ``removed_job``; ``pause``/``resume`` → ``job``. A tool-level failure lands in ``error``. */
export interface CronManageResult {
success?: boolean | null
error?: string | null
count?: number | null
jobs?: CronJobRow[] | null
scoped?: string | null
gateway_running?: boolean | null
warning?: string | null
job_id?: string | null
name?: string | null
skill?: string | null
skills?: string[] | null
schedule?: string | null
repeat?: number | string | null
deliver?: string | null
next_run_at?: string | null
job?: CronJobRow | null
message?: string | null
guidance?: unknown | null
removed_job?: CronRemovedJob | null
[key: string]: unknown
}
/** ``tools/cronjob_job_args.py::_format_job``. */
export interface CronJobRow {
job_id: string
name?: string
skill?: string | null
skills?: string[]
prompt_preview?: string
model?: string | null
provider?: string | null
base_url?: string | null
schedule?: string
repeat?: number | string | null
deliver?: string | null
next_run_at?: string | null
last_run_at?: string | null
last_status?: string | null
last_delivery_error?: string | null
last_delivery_unverified?: string[] | null
last_fire_error?: string | null
last_error?: string | null
enabled?: boolean
state?: string | null
paused_at?: string | null
paused_reason?: string | null
workdir?: string | null
script?: string | null
reasoning_effort?: string | null
monitor_script?: string | null
monitor_url?: string | null
monitor_state?: unknown | null
no_agent?: boolean | null
enabled_toolsets?: string[] | null
continuity?: boolean | null
context_from?: string[] | null
attach_to_session?: boolean | null
[key: string]: unknown
}
export interface CronRemovedJob {
id: string
name?: string
schedule?: string | null
}
export interface BrowserManageParams {
action?: BrowserAction
url?: string | null
session_id?: string | null
profile?: string | null
}
export type BrowserAction = 'status' | 'connect' | 'disconnect'
export interface BrowserManageResult {
connected: boolean
url?: string | null
messages?: string[] | null
}
/** Handlers that look a live session up with ``_sessions.get(params.get("session_id"))``: an absent / unknown id falls back to the launch profile's config, so it is never required. */
export interface _SessionScoped {
session_id?: string | null
}
export interface ToolsetsListResult {
toolsets: ToolsetRow[]
}
/** One row of ``methods_tools._toolset_rows``; ``tools`` only when the caller asked for them (``tools.list``). */
export interface ToolsetRow {
name: string
description: string
tool_count: number
enabled: boolean
tools?: string[] | null
}
export interface ToolsShowResult {
sections: ToolShowSection[]
total: number
}
export interface ToolShowSection {
name: string
tools: ToolShowRow[]
}
export interface ToolShowRow {
name: string
description: string
}
/** ``names`` are toolset keys or ``server:tool`` MCP targets; with ``session_id`` the live session's profile is authoritative and its agent is rebuilt. */
export interface ToolsConfigureParams {
action: ToolsAction
names: string[]
session_id?: string | null
profile?: string | null
}
export type ToolsAction = 'enable' | 'disable'
export interface ToolsConfigureResult {
changed: string[]
enabled_toolsets: string[]
info?: SessionLiveInfo | null
missing_servers: string[]
reset: boolean
unknown: string[]
}
/** The shared owner serves ``/reload`` for one session the caller controls (``session_id``). */
export interface ReloadEnvParams {
session_id?: string | null
profile?: string | null
}
export interface ReloadEnvResult {
updated: number
}
/** Without ``confirm`` the handler may answer ``confirm_required`` (per ``approvals.mcp_reload_confirm``); ``always`` persists the opt-out; ``rev`` is the config revision the caller wants loaded (coalescing). */
export interface ReloadMcpParams {
session_id?: string | null
confirm?: boolean
always?: boolean
rev?: string | null
}
/** ``session``: what the calling local session's MCP servers did (a new policy generation, nothing to change, or deferred while a turn runs or waits); ``unavailable``: configured servers that did not connect beside what did apply; ``session_servers``: the MCP servers that session's committed policy runs. */
export interface ReloadMcpResult {
status: ReloadMcpStatus
message?: string | null
loaded_rev?: string | null
coalesced?: boolean | null
turn_isolation?: boolean | null
host_ack?: unknown | null
session?: ReloadMcpSession | null
unavailable?: string[] | null
session_servers?: string[] | null
}
export type ReloadMcpStatus = 'confirm_required' | 'reloaded'
export type ReloadMcpSession = 'applied' | 'unchanged' | 'busy'
/** ``query`` is the search text / hub identifier / browse page (digits); ``page`` / ``page_size`` apply to ``browse``. */
export interface SkillsManageParams {
profile?: string | null
action?: SkillsAction
query?: string | null
page?: number | null
page_size?: number | null
}
export type SkillsAction = 'list' | 'search' | 'install' | 'browse' | 'inspect'
/** Shape follows the action: ``list`` → ``skills`` (category → names); ``search`` → ``results``; ``install`` → ``installed`` + ``name``; ``browse`` → ``items`` + paging; ``inspect`` → ``info``. */
export interface SkillsManageResult {
skills?: Record<string, string[]> | null
results?: SkillHubHit[] | null
installed?: boolean | null
name?: string | null
items?: SkillBrowseItem[] | null
page?: number | null
total_pages?: number | null
total?: number | null
info?: SkillInspectInfo | null
}
export interface SkillHubHit {
name: string
description: string
}
/** ``hermes_cli.skills_hub.browse_skills`` row. */
export interface SkillBrowseItem {
name?: string
description?: string
source?: string
trust?: string | null
identifier?: string | null
[key: string]: unknown
}
/** ``hermes_cli.skills_hub.inspect_skill``; ``{}`` when the identifier resolves nowhere. */
export interface SkillInspectInfo {
name?: string | null
description?: string | null
source?: string | null
identifier?: string | null
tags?: string[] | null
skill_md_preview?: string | null
[key: string]: unknown
}
/** ``session_id`` binds the rescan to that session's profile and workspace (project skills); ``profile`` scopes a session-less rescan. */
export interface SkillsReloadParams {
session_id?: string | null
profile?: string | null
}
export interface SkillsReloadResult {
output: string
result: SkillsReloadDiff
}
/** ``agent.skill_commands.reload_skills``. */
export interface SkillsReloadDiff {
added?: SkillCommandRef[]
removed?: SkillCommandRef[]
unchanged?: string[]
total?: number
commands?: number
[key: string]: unknown
}
export interface SkillCommandRef {
name: string
description?: string
}
export interface LearningFramesParams {
cols?: number | null
rows?: number | null
frames?: number | null
}
export interface LearningFramesResult {
frames: LearningFrame[]
legend: LearningLegendItem[]
categories: LearningLegendItem[]
buckets: LearningBucketRow[]
summary: string[]
axis: LearningAxis
count: number
cols: number
rows: number
}
/** ``agent.learning_graph_render.render_graph`` projection; ``grid`` rows are lists of ``[text, styleKey, alpha?, hexOverride?]`` runs. */
export interface LearningFrame {
reveal: number
date: string
visible: number
grid: unknown[][]
labels?: Record<string, unknown>[]
}
export interface LearningLegendItem {
glyph: string
label: string
style?: string | null
color?: string | null
}
export interface LearningBucketRow {
index: number
label: string
date: string
skills: number
memories: number
total: number
category?: string | null
color?: string | null
nodes: LearningNodeRow[]
}
export interface LearningNodeRow {
id: string
glyph: string
label: string
fullLabel: string
meta: string
body: string
style: string
}
export interface LearningAxis {
start: string
end: string
}
export interface LearningNodeParams {
id?: string | null
}
export interface LearningDetailResult {
ok: boolean
message?: string | null
kind?: string | null
id?: string | null
label?: string | null
content?: string | null
}
/** ``agent.learning_mutations`` — ``ok: false`` carries the reason in ``message``. */
export interface LearningMutationResult {
ok: boolean
message?: string | null
}
export interface LearningEditParams {
id?: string | null
content?: string | null
}
export interface McpCatalogResult {
servers: McpCatalogEntry[]
}
export interface McpCatalogEntry {
name: string
description: string
connector_slug?: string | null
installed: boolean
enabled: boolean
requires: string[]
transport: string
}
export interface McpServersListResult {
servers: McpServerSummary[]
}
/** ``tui_gateway/mcp_rpc_helpers.summarize_server`` — a server's config without secret values. */
export interface McpServerSummary {
name: string
transport: string
url?: string | null
command?: string | null
args: string[]
env: string[]
auth?: string | null
oauth_tokens_present?: boolean | null
enabled: boolean
tools?: unknown | null
source: McpServerSource
plugin?: string | null
}
export type McpServerSource = 'config' | 'plugin'
export interface McpServersStatusResult {
servers: McpServerRuntimeRow[]
checked_at: number
}
/** Safe projection of ``tools.mcp_tool_discovery.get_mcp_status`` rows. */
export interface McpServerRuntimeRow {
name: string
transport: string
tools: number
connected: boolean
disabled: boolean
status: McpRuntimeStatus
source: McpServerSource
plugin?: string | null
}
export type McpRuntimeStatus = 'connected' | 'disabled' | 'connecting' | 'failed' | 'lazy' | 'configured'
/** ``preset`` (catalog id) and/or ``config`` (url/command/args/env/headers/auth/tools); a ``bearer_token`` is written to the profile's .env, only the header template persists. */
export interface McpServersAddParams {
profile?: string | null
name: string
preset?: string | null
config?: Record<string, unknown> | null
bearer_token?: string | null
}
export interface McpServersAddResult {
ok: boolean
name: string
server: McpServerSummary
}
export interface McpServersSetApiKeyParams {
profile?: string | null
name: string
value: string
env_var?: string | null
}
export interface McpServersSetApiKeyResult {
ok: boolean
name: string
env_var: string
server: McpServerSummary
}
export interface McpServerNameParams {
profile?: string | null
name: string
}
/** ``ok: false`` carries ``error``; ``prompts`` / ``resources`` are only counted on success. */
export interface McpServersTestResult {
ok: boolean
tools: McpProbeTool[]
error?: string | null
prompts?: number | null
resources?: number | null
oauth_needed: boolean
oauth_tokens_present?: boolean | null
}
export interface McpProbeTool {
name: string
description: string
}
export interface McpServersRemoveResult {
ok: boolean
removed: boolean
}
/** With ``client_redirect_uri`` the CLIENT hosts the loopback and relays the code via ``mcp.servers.oauth.callback``. */
export interface McpOauthStartParams {
profile?: string | null
name: string
client_redirect_uri?: string | null
}
export interface McpOauthStartResult {
ok: boolean
session_id: string
auth_url: string
flow: string
}
/** ``session_id`` is the OAuth flow id returned by ``oauth.start`` (not a gateway session). */
export interface McpOauthFlowParams {
profile?: string | null
name: string
session_id: string
}
export interface McpOauthPollResult {
ok: boolean
status: McpOauthPollStatus
session_id?: string | null
error_message?: string | null
auth_url?: string | null
tools?: McpProbeTool[] | null
}
export type McpOauthPollStatus = 'pending' | 'approved' | 'error'
export interface McpOauthCancelResult {
ok: boolean
status?: string | null
error_message?: string | null
}
export interface McpOauthCallbackParams {
profile?: string | null
name: string
session_id: string
code?: string | null
state?: string | null
error?: string | null
iss?: string | null
}
export interface McpOauthCallbackResult {
ok: boolean
session_id?: string | null
error_message?: string | null
}
export type PluginsListParams = Record<string, never>
export interface PluginsListResult {
plugins: LegacyPluginRow[]
toolsets?: PluginToolsetRow[] | null
portable_mcp_servers?: string[] | null
}
export interface LegacyPluginRow {
name: string
version: string
enabled: boolean
key?: string | null
tools?: number | null
hooks?: number | null
commands?: number | null
error?: string | null
}
export interface PluginToolsetRow {
key: string
label: string
description: string
}
/** ``toggle``: ``key``/``name`` + ``enable``; ``install``: ``identifier``/``repo`` or ``catalog_name`` (+ ``force``, ``enable``, ``ref``, ``inspected_sha`` = the commit ``inspect`` read: a custom source with no ``ref`` whose branch moved since is refused); ``inspect``: ``identifier``/``repo`` or ``catalog_name``; ``install_desktop``: ``identifier``/``repo`` (any source ``install`` takes) or ``catalog_name``, always with ``ref`` (the commit ``inspect`` read and the dialog showed; another commit is refused) (+ ``force``) — the desktop half onto the host that serves this client; ``remove_desktop``: ``name`` (+ ``force`` for a package's own half); ``update``: ``name`` (+ ``accept_capabilities`` to apply a re-pin that widened the plugin after the user confirmed the ``delta``, + ``force`` to apply an update whose security scan returned caution after the user saw the findings); ``remove``: ``name`` (user installs only); ``settings``: ``key`` + ``values`` (``{setting_key: value}``, non-secret schema keys only); ``presence``: ``names`` (catalog names, answered in that order). */
export interface PluginsManageParams {
profile?: string | null
action?: PluginsAction
key?: string | null
name?: string | null
enable?: boolean | null
identifier?: string | null
repo?: string | null
catalog_name?: string | null
force?: boolean | null
ref?: string | null
inspected_sha?: string | null
accept_capabilities?: boolean | null
values?: Record<string, unknown> | null
names?: string[] | null
}
export type PluginsAction = 'list' | 'toggle' | 'install' | 'inspect' | 'install_desktop' | 'remove_desktop' | 'update' | 'remove' | 'settings' | 'onboarding' | 'presence'
/** ``list`` → ``plugins`` + counts; ``toggle`` → ``ok``/``unchanged``/``restart_required``/``name`` (the canonical key written)/``plugin``; ``install`` → ``hermes_cli.plugins_cmd.dashboard_install_plugin``'s ok payload; ``inspect`` → ``ok``/``agent``/``desktop``/``agent_name``/``desktop_name``/``sha`` (the commit read)/``warnings``/``insecure`` or ``ok=false`` + ``error``; ``toggle``/``install``/``update`` that loaded a plugin also carry ``gateway_reloaded`` (the running gateway picked it up and re-wired its handlers) and ``activation`` — the honest split of what is live now vs deferred, so ``restart_required`` is True only when no gateway answered or the running gateway/backend cannot import the plugin's Python dependencies (``activation.missing_dependencies``); ``update`` → ``ok``/``unchanged``/``sha``, or ``ok=false`` + ``consent_required`` with the ``delta`` (``{surface: [added...]}``) / ``delta_lines`` a widened pin adds — nothing changed until the client retries with ``accept_capabilities`` — or ``ok=false`` + ``scan_blocked`` with ``scan_verdict`` / ``scan_findings`` (retry a caution verdict with ``force``); ``remove`` → ``ok``/``name`` plus ``cleared_memory_provider`` when the removed plugin was the live ``memory.provider``. */
export interface PluginsManageResult {
plugins?: AgentPluginRow[] | null
user_count?: number | null
bundled_count?: number | null
ok?: boolean | null
unchanged?: boolean | null
restart_required?: boolean | null
gateway_reloaded?: boolean | null
activation?: PluginActivation | null
cleared_memory_provider?: boolean | null
name?: string | null
plugin?: AgentPluginRow | null
plugin_name?: string | null
warnings?: string[] | null
missing_env?: string[] | null
python_dependencies?: string[] | null
known_issues?: string[] | null
after_install_path?: string | null
enabled?: boolean | null
sha?: string | null
consent_required?: boolean | null
delta?: Record<string, string[]> | null
delta_lines?: string[] | null
scan_blocked?: boolean | null
scan_verdict?: string | null
scan_findings?: PluginScanFinding[] | null
error?: string | null
written?: string[] | null
onboarding?: OnboardingCatalogPlugin[] | null
presence?: CatalogPluginPresence[] | null
agent?: boolean | null
desktop?: boolean | null
agent_name?: string | null
desktop_name?: string | null
insecure?: boolean | null
path?: string | null
paired_with_agent?: boolean | null
unpaired_from?: string | null
}
/** ``methods_tools._plugin_rows`` + ``plugins_cmd_catalog.catalog_row_fields`` provenance. */
export interface AgentPluginRow {
name: string
key: string
version: string
description: string
source: string
status: string
portable: boolean
install_dir: string
has_desktop_half: boolean
servers: PluginServerRow[]
catalog_name?: string | null
catalog_tier?: string | null
installed_sha?: string | null
catalog_sha?: string | null
catalog_version?: string | null
update_available?: boolean | null
update_target?: string | null
pinned_sha?: string | null
settings_schema?: PluginSettingField[] | null
tools?: string[]
}
export interface PluginServerRow {
name: string
state: PluginServerState
sentence: string
}
export type PluginServerState = 'connected' | 'app_not_running' | 'hermes_not_connected' | 'endpoint_unavailable' | 'no_interactive_session' | 'version_too_old' | 'missing_app' | 'unsupported_gpu' | 'unknown'
/** One ``config_schema`` key of a plugin manifest, rendered by the Plugins hub (``hermes_cli.plugins_settings.plugin_settings_fields``). ``secret`` fields carry no value: ``env`` names the ``.env`` variable and ``has_value`` whether it is set. */
export interface PluginSettingField {
key: string
type: PluginSettingFieldType
label: string
description: string
required: boolean
value?: unknown | null
default?: unknown | null
choices?: string[] | null
env?: string | null
has_value?: boolean | null
}
export type PluginSettingFieldType = 'string' | 'number' | 'boolean' | 'enum' | 'secret' | 'json'
/** What a plugin loaded mid-run does NOW vs later (``hermes_cli.plugins_activation``). ``activated_now`` kinds (``{kind: [names]}``): ``gateway_commands`` (slash names), ``locales`` (``<lang>.<surface>`` language-pack layers), ``gateway_transforms`` / ``hooks`` (hook names), ``callbacks`` (platforms / ``slack:<action_id>``) — live in the running gateway once it reloaded (``gateway_reloaded``). ``live_now``: the plugin's MCP servers (connected, with their tools, or the error) and skills, usable in every open chat of the profile from its next turn — the chats also get a note listing them. ``deferred`` kinds: ``tools`` (Python tool names) and ``prompt`` (section ids) apply from the next session. ``missing_dependencies``: the plugin's declared Python requirements a running process cannot import (installed after it booted, or never); ``missing_in`` names which processes (``gateway``, ``backend`` = the Desktop / dashboard process) — only restarting them loads them. */
export interface PluginActivation {
name: string
key: string
activated_now?: Record<string, string[]>
live_now?: PluginLiveNow | null
deferred?: Record<string, string[]>
missing_dependencies?: string[]
missing_in?: PluginRestartTarget[]
}
export interface PluginLiveNow {
mcp_servers?: PluginLiveServer[]
skills?: PluginLiveSkill[]
}
/** One plugin MCP server connected at activation: its callable tool names, or the reason it did not connect. */
export interface PluginLiveServer {
name: string
connected: boolean
tools?: string[]
error?: string | null
}
/** One plugin skill usable now through ``skill_view`` (qualified ``<plugin>:<skill>``). */
export interface PluginLiveSkill {
name: string
description?: string
}
export type PluginRestartTarget = 'gateway' | 'backend'
/** One security-scan finding (``tools.plugin_guard``) on a plugin tree the scan blocked. */
export interface PluginScanFinding {
pattern_id: string
severity: string
category: string
file: string
line: number
description: string
}
/** A catalog plugin curated for the onboarding card (``onboarding: true``) that this OS runs. ``app_state`` is the pinned ``plugin.json`` declaration judged on this host; ``sentence`` names what is missing (empty when present or unknown). */
export interface OnboardingCatalogPlugin {
name: string
title: string
description: string
tier: CatalogTier
platforms: string[]
app_state: CatalogAppState
sentence: string
}
/** A named catalog plugin this OS runs. ``state`` is the pinned ``plugin.json`` app declaration judged on this host; ``sentence`` names what is missing (empty when present or unknown); ``disclosure`` is the catalog description's ``Disclosure:`` sentence (empty when it has none). */
export interface CatalogPluginPresence {
name: string
title: string
state: CatalogAppState
sentence: string
disclosure: string
}
export interface PluginCatalogLookupParams {
profile?: string | null
name: string
}
/** ``found`` carries ``entry``. ``unknown`` covers a name the catalog doesn't list and one it removed; ``unavailable`` means neither the live catalog nor the in-tree fallback could be read. */
export interface PluginCatalogLookupResult {
status: PluginCatalogLookupStatus
entry?: PluginCatalogLookupEntry | null
}
export type PluginCatalogLookupStatus = 'found' | 'invalid_name' | 'unknown' | 'unavailable'
/** The fields an install needs: the same ones the embedded catalog picker posts on a pick. */
export interface PluginCatalogLookupEntry {
name: string
repo: string
sha: string
subdir: string
tier?: string
}
export interface GroupsAttachmentUploadParams {
profile?: string | null
room_id: string
upload_id: string
kind: string
name: string
mime: string
data_base64: string
}
export interface RoomAttachment {
attachment_id: string
kind: string
name: string
size: number
mime: string
sha256: string
state: string
created_at: number
idempotent: boolean
event_id?: string | null
[key: string]: unknown
}
export interface GroupsAttachmentDownloadParams {
profile?: string | null
room_id: string
event_id: string
attachment_id: string
}
export interface RoomAttachmentBytes {
attachment_id: string
kind: string
name: string
size: number
mime: string
sha256: string
state: string
created_at: number
idempotent: boolean
event_id?: string | null
data_base64: string
[key: string]: unknown
}
export interface GroupsDiscardParams {
profile?: string | null
room_id: string
member_id: string
task_id: string
execution_generation: number
}
export interface GroupsDiscardResult {
discarded?: boolean
task: RoomTaskReceipt
}
export interface CanonicalShellExecParams {
session_id: string
command: string
profile?: string | null
}
export interface PromptReceiptParams {
session_id: string
admission_id: string
include_result?: boolean | null
}
/** ``result`` / ``usage``: the structured turn result committed at settlement, only with ``include_result`` on a terminal admission that saved one. */
export interface PromptReceiptResult {
admission_id: string
ref: CanonicalSessionRef
sequence: number
status: 'queued' | 'started' | 'unknown' | 'terminal'
outcome: string | null
authority_epoch: number
execution_generation: number | null
result?: unknown | null
usage?: Record<string, unknown> | null
}
export interface CanonicalSessionRef {
profile_id: string
session_id: string
}
export interface PromptCancelParams {
session_id: string
admission_id: string
}
/** ``gateway/session_contract.py::AdmissionReceipt`` as ``dataclasses.asdict`` sends it. */
export interface AdmissionStatus {
admission_id: string
ref: CanonicalSessionRef
sequence: number
status: 'queued' | 'started' | 'unknown' | 'terminal'
outcome: string | null
authority_epoch: number
execution_generation: number | null
}
export interface PromptResolveUnknownParams {
session_id: string
admission_id: string
execution_generation: number
}
/** ``operation`` + ``payload`` are validated by ``hermes_state_mutations.validate_action``; ``expected_generation`` is required for delete/rewind/reset/branch/model/compress/reasoning/workspace. ``reasoning`` (``{effort}``) and ``workspace`` (``{cwd}``, refused ``session_busy`` mid-turn) rewrite the session's frozen policy: session-scope ``/reasoning`` and Desktop's Move to project. ``edit_policy`` (``{policy}``: ask / workspace_session / session) is an ACP session's edit approval (main's ACP modes). */
export interface SessionMutateParams {
session_id: string
request_id: string
expected_revision: number
operation: string
payload: Record<string, unknown>
expected_generation?: number | null
}
/** The committed mutation receipt plus the operation's projection (``title``, ``archived``, ``branched_session_id``, compress ``status``/``lines``, …). ``revision`` is absent only on a read-only compress preview. */
export interface SessionMutateResult {
session_id: string
operation: string
revision?: number | null
[key: string]: unknown
}
/** Exactly one of ``filters`` (``SessionDB.prune_sessions`` keyword filters, as ``hermes sessions prune`` builds them) or ``never_active_days`` (``--never-active``). */
export interface SessionPruneParams {
filters?: Record<string, unknown> | null
never_active_days?: number | null
}
export interface SessionPruneResult {
deleted: number
routing_deleted?: number | null
skipped?: number | null
}
export interface CommandObserveParams {
session_id: string
name: string
arg?: string | null
profile?: string | null
}
export interface CommandObserveResult {
queued: boolean
}
export interface CanonicalSessionInfoParams {
session_id: string
}
/** ``gateway/session_local_inventory.py::snapshot_info``: ``local_session_info`` + the inventory. */
export interface CanonicalSessionInfo {
provider?: string | null
tools?: Record<string, string[]> | null
skills?: Record<string, string[]> | null
mcp_servers?: McpServerStatus[] | null
version?: string | null
release_date?: string | null
update_behind?: unknown | null
update_command?: string | null
branch?: string | null
project?: ProjectRef | null
system_prompt?: string | null
context_length?: number | null
enabled_toolsets?: string[] | null
tool_availability?: Record<string, unknown> | null
tool_availability_warnings?: string[] | null
unknown_toolsets?: string[] | null
source: string
model?: string | null
lazy: boolean
profile_id: string
desktop_protocol: string
profile_name: string
cwd?: string | null
edit_approval_policy?: 'ask' | 'workspace_session' | 'session' | null
launch_request?: Record<string, unknown> | null
reasoning_effort?: string | null
reasoning_effort_wire?: string | null
service_tier?: string | null
fast?: boolean | null
title?: string | null
started_at?: number | null
last_active_at?: number | null
yolo?: boolean | null
api_mode?: string | null
tool_count?: number | null
credential_hint?: string | null
config_warning?: string | null
[key: string]: unknown
}
export interface SessionStatsParams {
session_id: string
}
/** ``gateway/session_usage.py::usage_stats``: session-cumulative counters (the agent's ``session_*``), context / compressor figures, rolling latency and throughput, rate-limit state, live subagents. */
export interface SessionStats {
input_tokens: number
output_tokens: number
cache_read_tokens: number
cache_write_tokens: number
prompt_tokens: number
completion_tokens: number
total_tokens: number
reasoning_tokens: number
api_calls: number
last_prompt_tokens: number
context_tokens: number
context_length?: number | null
config_context_length?: number | null
context_source?: string | null
compression_count: number
avg_latency_s?: number | null
tokens_per_s?: number | null
last_turn_tokens: number
rate_limit?: Record<string, unknown> | null
active_subagents: number
model: string
provider: string
fallback_model?: string | null
plan_gauge?: PlanGauge | null
}
export interface RollbackSessionDiffParams {
session_id: string
profile?: string | null
}
/** ``gateway/session_tui_ops.py::_session_diff``: ``CheckpointManager.session_diff`` under the session's frozen checkpoint policy (``enabled: false`` when that policy does not checkpoint). ``diff`` is bounded to fit one frame; ``diff_lines`` counts the whole body. */
export interface RollbackSessionDiffResult {
enabled: boolean
success?: boolean
stat?: string
diff?: string
diff_lines?: number
empty?: boolean
error?: string | null
}
/** ``format``: json (default) / md / markdown / html / snapshot (``normalize_save_format``). */
export interface SessionExportParams {
session_id: string
profile?: string | null
format?: string
redact?: boolean
}
/** ``gateway/session_tui_ops.py::export_session``: the rendered ``/save`` body and its default file name. The client writes it (the gateway may be remote); nothing is written on the host. */
export interface SessionExportResult {
format: string
filename: string
content: string
}
export interface SessionAutomationParams {
session_id: string
kind: 'goal' | 'loop' | 'heartbeat'
call: string
args?: unknown[] | null
kwargs?: Record<string, unknown> | null
}
/** ``gateway/session_viewer_automation.py``: the manager's persisted state after the call (its own JSON, ``null`` when none) and the call's value, or the refusal main's manager raised. */
export interface SessionAutomationResult {
state: string | null
value?: unknown | null
error?: Record<string, string> | null
}
export interface SessionDetachParams {
session_id: string
subscription_id: string
end_reason?: string | null
}
export interface SessionDetachResult {
session_id: string
subscription_id: string
detached: boolean
}
export type RuntimeDescribeParams = Record<string, never>
export interface RuntimeDescribeResult {
instance_id: string
profile_id: string
authority_epoch: number
capabilities: string[]
session_create: SessionCreateDescriptor
skin?: SkinPayload | null
}
export interface SessionCreateDescriptor {
sources: string[]
parameters: string[]
}
/** ``tui_gateway/change_watcher.py::resolve_skin`` — the resolved active skin (``HermesSkin``). ``{}`` when the skin engine failed to load. Colour maps are token → colour string. */
export interface SkinPayload {
name?: string
description?: string
colors?: Record<string, string>
light_colors?: Record<string, string>
dark_colors?: Record<string, string>
branding?: Record<string, string>
banner_logo?: string
banner_hero?: string
tool_prefix?: string
help_header?: string
[key: string]: unknown
}
export interface ClarifyRespondParams {
session_id: string
execution_generation: number
prompt_id: string
answer: string
}
export interface PromptResponseResult {
status: 'resolved' | 'already_resolved'
prompt_id: string
}
export interface CronRunParams {
job_id: string
request_id: string
extra_prompt: string | null
}
export interface CronSubmitResult {
session_id: string
admission_id: string
}
/** ``result`` is the ``run_job`` tuple once terminal; ``recover`` adds the frozen ``job`` and answers ``status='missing'`` for a firing that was never admitted. */
export interface CronStatusResult {
status: string
result: unknown[] | null
job_flags?: Record<string, unknown> | null
job?: Record<string, unknown> | null
[key: string]: unknown
}
export interface CronAdmissionParams {
session_id: string
admission_id: string
}
export interface CronCancelResult {
ok: boolean
}
export interface KanbanRunParams {
board: string
task_id: string
run_id: number
claim_lock: string
db?: string | null
}
export interface KanbanRunResult {
session_id: string
receipt: AdmissionStatus
}
export interface A2aForwardParams {
agent: string
tenant: string
peer: string
context_id: string
input_id: string
text: string
}
export interface A2aForwardResult {
admission_id: string
ref: CanonicalSessionRef
sequence: number
status: 'queued' | 'started' | 'unknown' | 'terminal'
outcome: string | null
authority_epoch: number
execution_generation: number | null
session_id: string
result: unknown | null
}
export interface WorkerRegisterParams {
profile_id: string
session_id: string
execution_id: string
generation: number
pid: number
birth: number
secret: string
kind: string
}
/** A ``worker_executions`` row without its adoption digest. */
export interface WorkerExecution {
execution_id: string
session_id: string
kind: string
owner_epoch: number
generation: number
status: string
last_sequence: number
[key: string]: unknown
}
/** The producer claim every worker verb proves (``gateway/session_worker.py::_SCOPE``). */
export interface WorkerScopeParams {
profile_id: string
session_id: string
execution_id: string
generation: number
pid: number
birth: number
secret: string
}
export interface WorkerPersistParams {
profile_id: string
session_id: string
execution_id: string
generation: number
pid: number
birth: number
secret: string
epoch: number
sequence: number
operation: string
payload: Record<string, unknown>
}
/** The operation's durable receipt (``message_id`` for an append, delegation results, …). */
export type WorkerPersistResult = Record<string, unknown>
export interface CanonicalCreateParams {
profile?: string | null
request_id?: string | null
source?: 'cli' | 'tui' | 'gui' | 'acp' | 'tool' | 'oneshot'
cwd?: string | null
row_cwd?: string | null
model?: string | null
provider?: string | null
base_url?: string | null
api_key?: string | null
toolsets?: string[] | null
reasoning?: string | null
max_turns?: number | string | null
ignore_rules?: boolean
yolo?: boolean
safe_mode?: boolean
ignore_user_config?: boolean
skills?: string[] | null
checkpoints?: boolean
accept_hooks?: boolean
pass_session_id?: boolean
editor?: Record<string, unknown> | null
title?: string | null
hidden?: boolean
follow_profile_config?: boolean | null
service_tier?: string | null
cwd_explicit?: boolean | null
run_budget?: number | null
verbose?: boolean
client_env?: Record<string, string> | null
}
export interface CanonicalSnapshot {
session_id: string
stored_session_id: string
messages: TranscriptMessage[]
messages_omitted?: boolean | null
display_messages?: TranscriptMessage[] | null
message_count: number
running: boolean
authority_epoch: number
replay_epoch: string
last_sequence: number
subscription_id: string
revision: number
execution_generation: number
pending: CanonicalPendingAdmission[]
prompts: CanonicalPendingPrompt[]
info: CanonicalSnapshotInfo
pending_connection?: ConnectionRequestPayload | null
todo_state?: TodoState | null
open_requests?: OpenRequestEntry[] | null
}
export interface CanonicalPendingAdmission {
admission_id: string
ref: CanonicalSessionRef
sequence: number
status: 'queued' | 'started' | 'unknown' | 'terminal'
outcome: string | null
authority_epoch: number
execution_generation: number | null
input_id: string
text: string
controls?: ('steer' | 'replace')[] | null
steering?: boolean | null
}
export interface CanonicalPendingPrompt {
kind: 'approval' | 'clarify'
prompt_id: string
execution_generation: number
choices: string[]
command?: string | null
description?: string | null
edit?: Record<string, unknown> | null
question?: string | null
multi_select?: boolean | null
timeout_s?: number | null
}
export interface CanonicalSnapshotInfo {
provider?: string | null
tools?: Record<string, string[]> | null
skills?: Record<string, string[]> | null
mcp_servers?: McpServerStatus[] | null
version?: string | null
release_date?: string | null
update_behind?: unknown | null
update_command?: string | null
branch?: string | null
project?: ProjectRef | null
system_prompt?: string | null
context_length?: number | null
enabled_toolsets?: string[] | null
tool_availability?: Record<string, unknown> | null
tool_availability_warnings?: string[] | null
unknown_toolsets?: string[] | null
desktop_protocol: 'hermes-gateway-v1'
source?: string | null
model?: string | null
lazy?: boolean | null
profile_id?: string | null
profile_name?: string | null
cwd?: string | null
edit_approval_policy?: 'ask' | 'workspace_session' | 'session' | null
launch_request?: Record<string, unknown> | null
reasoning_effort?: string | null
reasoning_effort_wire?: string | null
service_tier?: string | null
fast?: boolean | null
title?: string | null
started_at?: number | null
last_active_at?: number | null
yolo?: boolean | null
api_mode?: string | null
tool_count?: number | null
credential_hint?: string | null
config_warning?: string | null
}
export interface CanonicalResumeParams {
profile?: string | null
session_id?: string
title?: string | null
latest?: 'cli' | 'tui' | null
workspace?: string | null
source?: string | null
editor?: Record<string, unknown> | null
api_key?: string | null
defer_history?: boolean
omit_messages?: boolean
cols?: number | null
display_projection?: boolean
}
export interface CanonicalListParams {
profile?: string | null
scope?: 'live' | 'stored'
limit?: number
title?: string | null
include_hidden?: boolean
}
export interface CanonicalListResult {
sessions: CanonicalSessionListRow[]
scope: 'stored' | 'live'
}
export interface CanonicalSessionListRow {
session_id: string
id: string
title: string
source: string | null
started_at: number | null
message_count: number
running: boolean
model?: string | null
resolved_id?: string | null
root_title?: string | null
}
export interface CanonicalControlParams {
profile?: string | null
session_id: string
execution_generation: number
}
export interface CanonicalSessionHandle {
ref: CanonicalSessionRef
instance_id: string
authority_epoch: number
revision: number
execution_generation: number
execution_state: 'idle' | 'running' | 'waiting' | 'unknown' | 'terminal'
}
export interface CanonicalCorrectionParams {
profile?: string | null
session_id: string
execution_generation: number
text: string
}
/** ``session.steer`` / ``session.redirect``: the correction verdict, or ``{voice_stopped: true}`` when the busy-time text was a bare stop phrase that ended the LOCAL voice chat. */
export type CanonicalCorrectionResult = CanonicalCorrectionAck | CanonicalVoiceStopped
export interface CanonicalCorrectionAck {
status: 'queued' | 'redirected' | 'rejected'
text: string
execution_generation: number
authority_epoch: number
delivered?: false | null
}
/** A bare stop phrase typed while the session's voice chat is on: the chat ended, nothing was admitted (TUI-26). */
export interface CanonicalVoiceStopped {
voice_stopped: true
}
export interface CanonicalEventsParams {
profile?: string | null
session_id: string
last_sequence?: number
last_seen?: number
replay_epoch?: string | null
}
export interface CanonicalEventsResult {
events: CanonicalReplayEvent[]
latest_seq: number
last_sequence: number
epoch: string
replay_epoch: string
truncated: boolean
snapshot_required: boolean
count: number
open_requests?: OpenRequestEntry[] | null
}
export interface CanonicalReplayEvent {
type: string
session_id: string
payload: Record<string, unknown>
replay_epoch: string
seq: number
authority_epoch?: number | null
execution_generation?: number | null
admission_id?: string | null
}
export interface CanonicalSubmitParams {
profile?: string | null
session_id: string
text: string
submission_id?: string | null
input_id?: string | null
queued?: boolean
attachments?: CanonicalAttachment[] | null
finite?: boolean
unattended?: boolean
surface?: string | null
voice_context?: string | null
interrupted?: boolean
voice_turn?: boolean
display_kind?: 'hidden' | null
title_preview?: string | null
turn_author?: CanonicalTurnAuthor | null
api_text?: string | null
model_override?: CanonicalModelOverride | null
clarify_batch?: boolean
}
export interface CanonicalAttachment {
path: string
mime: string
}
export interface CanonicalTurnAuthor {
id?: string | null
name?: string | null
is_bot?: boolean
origin?: string | null
}
export interface CanonicalModelOverride {
model: string
provider?: string | null
reasoning?: string | null
}
/** ``prompt.submit``: the admission receipt, or ``{voice_stopped: true}``. */
export type CanonicalSubmitResult = AdmissionStatus | CanonicalVoiceStopped
export interface CanonicalApprovalParams {
profile?: string | null
session_id: string
execution_generation: number
prompt_id: string
choice: string
}
export interface CanonicalSteerQueuedParams {
profile?: string | null
session_id: string
admission_id: string
}
/** The edited prompt: admitted as a NEW admission (``submission_id``) at the FIFO tail. */
export interface CanonicalReplaceQueuedParams {
profile?: string | null
session_id: string
admission_id: string
submission_id: string
text: string
attachments?: CanonicalAttachment[] | null
display_kind?: 'hidden' | null
title_preview?: string | null
}
export interface CanonicalConfigGetResult {
value?: string | null
display?: string | null
tool_progress?: string | null
model?: string | null
provider?: string | null
providers?: ConfigProviderRef[] | null
home?: string | null
cwd?: string | null
branch?: string | null
config?: Record<string, unknown> | null
prompt?: string | null
mtime?: number | null
mcp_rev?: string | null
key?: string | null
scope?: string | null
}
/** Session controls (``busy`` / ``verbose`` / ``yolo`` / ``show_reasoning`` / ``service_tier``, which need ``session_id``) and the TUI's profile preferences (``gateway/session_tui_config.py``; ``session_id`` optional). ``model`` is recognised only to be refused with ``use_session_mutation_model``: a model pick is the revision-fenced ``session.mutate`` operation, never a config write. */
export interface CanonicalConfigSetParams {
profile?: string | null
session_id?: string | null
key: string
value?: unknown
confirm_expensive_model?: boolean | null
scope?: 'session' | 'global' | null
}
export interface CanonicalProfilesParams {
profile?: string | null
include_sessions?: boolean
}
export interface CanonicalProfilesResult {
profiles: CanonicalProfileRow[]
bot_mode_protocol?: boolean
install_id?: string
}
export interface CanonicalProfileRow {
name: string
path: string
is_default?: boolean
model?: string | null
provider?: string | null
description?: string
display_name?: string
skill_count?: number
previous_names?: string[]
last_session?: ProfileCanonicalSession | null
worker_session?: ProfileWorkerSession | null
canonical_session?: ProfileCanonicalSession | null
ui_meta_revisions?: Record<string, number>
ui_meta?: Record<string, unknown> | null
has_avatar?: boolean
}
export interface CanonicalAttachedImageResult {
name?: string | null
width?: number | null
height?: number | null
token_estimate?: number | null
attached: boolean
path?: string | null
count?: number | null
remainder?: string | null
text?: string | null
bytes?: number | null
message?: string | null
mime: string
}
export interface CanonicalRoomAttemptParams {
profile?: string | null
room_id: string
member_id: string
task_id: string
execution_generation: number
}
export interface CanonicalRoomCreateParams {
profile?: string | null
room_id: string
name: string
members: RoomMemberInput[]
}
export interface CanonicalRoomApproveParams {
profile?: string | null
room_id: string
member_id: string
task_id: string
execution_generation: number
choice: 'once' | 'deny'
request_id: string
}
export interface CanonicalBotDeliverParams {
profile?: string | null
message: string
id: string
session_id?: string | null
author?: Record<string, unknown> | null
notification_category?: string | null
}
/** A delivery's receipt. It names its admission, unless ``refused``: the FIFO refused the delivery before anything was committed (``gateway/session_bot.py``), a terminal ``failed`` receipt with no admission that the relay settles as the sender's answer. */
export interface CanonicalBotDeliverResult {
status: string
delivery_id: string
profile_home: string
session_id: string
admission_id?: string | null
refused?: true | null
message: string
reply?: string | null
retry_admission_id?: string | null
error?: string | null
reason?: string | null
}
/** ``answers`` rides only on a reconnect replay (locks the server already accepted; null = skipped). */
export interface ClarifyRequestParams {
session_id: string
questions: ClarifyQuestion[]
answers?: Record<string, string | null> | null
}
export interface ClarifyQuestion {
qid: string
question: string
choices?: string[] | null
multi_select?: boolean
}
/** ``{answers}`` for the whole set (early locks go through the ``clarify.lock`` RPC); a response without ``answers`` is cancel-all. ``outcome`` (optional): how the viewer's own panel ended, as main's classic CLI reports it (``timed_out`` keeps the answers locked before its deadline). */
export interface ClarifyResult {
answers?: Record<string, string | null> | null
outcome?: 'submitted' | 'timed_out' | 'cancelled' | null
}
/** ``card`` is the beat's data (``agent/onboarding_flow.py::BEATS``): name, theme, connectors and plugins have their own shape; layout, tour and build carry ``options``. ``tool_call_id`` is the setup_beat call the card belongs to: only that transcript row draws it. */
export interface SetupBeatRequestParams {
session_id: string
beat: SetupBeat
question?: string | null
tool_call_id?: string | null
card: SetupNameCard | SetupThemeCard | SetupOptionsCard | SetupConnectorsCard | SetupPluginsCard
}
export type SetupBeat = 'name' | 'theme' | 'layout' | 'connectors' | 'plugins' | 'tour' | 'build'
export interface SetupNameCard {
suggested?: string | null
}
export interface SetupThemeCard {
picker: string
}
export interface SetupOptionsCard {
options: SetupOption[]
}
export interface SetupOption {
id: string
label: string
}
export interface SetupConnectorsCard {
suggested: string[]
}
export interface SetupPluginsCard {
plugins: string[]
}
/** ``answer`` holds the shown beat's picks; ids must be one of the card's options (the backend rejects any other answer). ``said`` is composer text typed while the name card waited: the name. ``wrote_instead``: the user sent a message instead of answering; the backend ends the turn and the client sends that message as the next one. A response with none of these, or none within 300 s, closes the card unanswered. */
export interface SetupBeatResult {
answer?: SetupNameAnswer | SetupThemeAnswer | SetupLayoutAnswer | SetupConnectorsAnswer | SetupPluginsAnswer | SetupTourAnswer | SetupBuildAnswer | null
said?: string | null
wrote_instead?: boolean
}
export interface SetupNameAnswer {
name: string
}
export interface SetupThemeAnswer {
accent?: string | null
mode?: string | null
}
export interface SetupLayoutAnswer {
layout: string
}
export interface SetupConnectorsAnswer {
connected: string[]
newly_connected?: string[]
}
export interface SetupPluginsAnswer {
installed: string[]
label?: string | null
}
export interface SetupTourAnswer {
tour: string
label?: string | null
}
export interface SetupBuildAnswer {
build: string
label?: string | null
}
/** ``tui_gateway/server.py::_approval_request_payload`` — the command is redacted server-side. */
export interface ApprovalRequestParams {
session_id: string
request_id: string
command?: string
description?: string
choices?: ApprovalChoice[]
allow_permanent?: boolean | null
allow_session?: boolean | null
smart_denied?: boolean | null
tool_name?: string | null
gateway_session_id?: string | null
[key: string]: unknown
}
export interface ApprovalResult {
choice: ApprovalChoice
all?: boolean | null
}
/** Original command, redacted server-side before any password-injection rewrite. */
export interface SudoRequestParams {
session_id: string
command?: string
}
/** The answer to any one-string prompt (sudo, secret, vault prompts, desktop bridges): ``''`` means skipped / declined. */
export interface ValueResult {
value: string
}
export interface SecretRequestParams {
session_id: string
env_var: string
prompt: string
metadata?: Record<string, unknown> | null
}
export interface VaultUnlockRequestParams {
session_id: string
backend: string
display_name: string
}
export interface VaultSaveLoginRequestParams {
session_id: string
origin: string
site: string
}
export interface VaultCodeRequestParams {
session_id: string
site?: string | null
hint?: string | null
}
export interface ReadRangeRequestParams {
session_id: string
start?: number | null
count?: number | null
}
export interface EmptyRequestParams {
session_id: string
}
/** ``tools/drive_preview_tool.py`` and ``tools/annotate_preview_tool.py`` field sets. */
export interface PreviewActRequestParams {
session_id: string
action: string
ref?: string | null
selector?: string | null
text?: string | null
key?: string | null
submit?: boolean | null
full?: boolean | null
to?: string | null
amount?: number | null
max?: number | null
allow_shortcut?: boolean | null
}
/** ``tools/tour_tool.py`` field set. */
export interface TourRequestParams {
session_id: string
action: string
surface?: string | null
selector?: string | null
title?: string | null
text?: string | null
side?: string | null
steps?: TourStep[] | null
step_index?: number | null
preset?: TourPreset | null
}
export interface TourStep {
selector?: string | null
title?: string | null
text?: string | null
side?: string | null
[key: string]: unknown
}
/** Which built-in tour ``start`` without steps runs. */
export type TourPreset = 'quick' | 'full'
/** ``tools/set_theme_tool.py`` values; accent is a swatch id, ``theme`` or ``#rrggbb``. */
export interface ThemeApplyRequestParams {
session_id: string
accent?: string | null
mode?: ThemeMode | null
layout?: string | null
}
export type ThemeMode = 'light' | 'dark' | 'system'
export interface ThemePickRequestParams {
session_id: string
picker: ThemePicker
}
export type ThemePicker = 'accent' | 'layout'
/** ``picked`` once the user chose (already applied); ``cancelled`` when the card was dismissed. A response with neither is a cancel. */
export interface ThemePickResult {
picked?: ThemeValues | null
said?: string | null
cancelled?: boolean | null
}
/** What the renderer applied. ``accent`` is a swatch id, ``custom:#rrggbb``, or null for the theme's own. */
export interface ThemeValues {
accent?: string | null
mode?: ThemeMode | null
layout?: string | null
}
export interface DisplayInstallSudoParams {
session_id: string
profile_key: string
}
/** ``methods_connectors._connection_update``: one target transition (``target``/``from``/``to``/ ``actor``) or the settlement (none of those), with the full snapshot. */
export interface ConnectionUpdatePayload {
op_id: string
seq: number
deadline_at: number
settled: boolean
settled_at?: number | null
settled_by?: ConnectionSettleReason | null
targets: ConnectionOperationTarget[]
owner: SessionOwner | AccountOwner
target?: string | null
from?: ConnectionTargetState | null
to?: ConnectionTargetState | null
actor?: ConnectionActor | null
detail?: string | null
}
/** ``tools/connectors/contract.py::Actor``. */
export type ConnectionActor = 'user' | 'backend_watcher' | 'clock'
export interface RequestCancelPayload {
id: string
method: string
reason: string
}
export interface DisplayStatusPayload {
profile: string
supported: boolean
installed: boolean
missing: string[]
running: boolean
pid?: number | null
display?: string | null
socket?: string | null
geometry: string
install_command?: string | null
browser?: string | null
blocker?: string | null
memory_available_mb?: number | null
memory_limit_mb?: number | null
placement?: string
image_switch?: DisplayImageSwitch | null
lease: DisplayLease
profile_key: string
}
export interface DisplayLeasePayload {
profile_key: string
lease: DisplayLease
}
export interface DisplayInstallLogPayload {
profile_key: string
line: string
}
export interface DisplayInstallDonePayload {
profile_key: string
code: number
status: DisplayStatus
}
/** ``tui_gateway/entry.py`` (stdio) / ``tui_gateway/ws.py`` (WebSocket) first frame. */
export interface GatewayReadyPayload {
skin: SkinPayload
change_events: boolean
replay_epoch: string
heartbeat?: boolean | null
session_authority?: boolean | null
}
/** ``agent/onboarding_record.py::_transition``: the run ``run_id`` stopped being in progress. ``stored_session_id`` is its chat at the compression tip. ``done``: the first-task card was answered; ``skipped``: Skip setup; ``replaced``: a rerun opened a new run; ``deleted``: its chat was deleted. */
export interface OnboardingEndedPayload {
run_id: string
stored_session_id: string
outcome: OnboardingOutcome
}
export type OnboardingOutcome = 'done' | 'skipped' | 'replaced' | 'deleted'
/** ``hermes_cli/free_tier_bootstrap.py::SetupRecord.as_payload``. */
export interface SetupReadyPayload {
provider_configured: boolean
inference_provider: string
free_tier_account: boolean
free_tier_route: boolean
has_identity: boolean
other_providers: boolean
error?: string
error_code?: string | null
retryable?: boolean | null
retry_after?: number | null
finished_at: number
[key: string]: unknown
}
/** Every ``_emit("error", …)`` site sets exactly ``message``. */
export interface ErrorPayload {
message: string
}
/** ``tui_gateway/model_switch.py`` capability-refresh notice. */
export interface NoticePayload {
message: string
}
/** ``message.start``. Empty from the TUI gateway's emitters and for an ordinary admission; ``gateway/session_authority._stamp_claim`` adds an automation admission's async-result card (``session_automation.admission_display``: a background-process completion) and its model text, so a viewer that did not submit the turn paints the same header the submitter would. */
export interface MessageStartPayload {
display_kind?: string | null
display_text?: string | null
notification_category?: string | null
text?: string | null
turn_id?: string | null
}
/** ``message.delta``. A session-authority local-viewer turn also publishes ``text: null``: the reply segment boundary (the agent's ``stream_delta_callback(None)``, before tool lines) that closes the classic CLI's reply box. Every other viewer ignores an empty chunk. A prompt turn stamps ``turn_id`` + ``segment`` (interim seals before it) + ``offset`` (UTF-16 code units of that segment already sent): a client drops a re-sent chunk it already applied. */
export interface MessageDeltaPayload {
text: string | null
rendered?: string | null
verbose?: boolean | null
turn_id?: string | null
segment?: number | null
offset?: number | null
}
/** ``prompt_turn._invoke_agent._stream`` (message.delta: ``text`` + optional ``rendered``), ``agent_callbacks._agent_cbs`` (reasoning.delta / thinking.delta), ``tool_progress._progress_reasoning`` (reasoning.available). ``verbose`` rides only when the session's verbose reasoning mode is on. */
export interface StreamDeltaPayload {
text: string
rendered?: string | null
verbose?: boolean | null
}
/** ``prompt_turn._interim_assistant_cb`` / ``agent_callbacks`` interim_assistant_callback. */
export interface MessageInterimPayload {
text: string
already_streamed: boolean
turn_id?: string | null
segment?: number | null
}
/** ``prompt_turn._complete_turn_payload`` / ``session_auto_continue._emit_terminal_turn_error`` / ``agent_callbacks._mirror_subagent_to_child`` (child watch mirror: ``text`` only) / ``compute_host_bridge`` (``text`` + ``status``). */
export interface MessageCompletePayload {
text?: string | unknown
usage?: Usage | null
status?: TurnStatus | null
reasoning?: string | null
warning?: string | null
response_previewed?: boolean | null
response_reused?: boolean | null
response_transformed?: boolean | null
billing?: BillingBlock | null
failure_reason?: string | null
rendered?: string | null
error?: string | null
recoverable?: boolean | null
error_surface?: ErrorSurface | null
partial?: boolean | null
persisted_turn?: PersistedTurn | null
}
/** ``prompt_turn._result_status``. */
export type TurnStatus = 'complete' | 'error' | 'interrupted'
/** ``agent/billing_links.py::BillingBlock.to_dict`` (+ ``unverified`` from conversation_loop). */
export interface BillingBlock {
provider: string
provider_label: string
model: string
billing_url: string | null
is_nous: boolean
message: string
unverified?: boolean | null
}
/** ``agent/error_surface.py::_surface`` — advisory {layer, code, retryable} (+ identity, + auth hint, + ``resets_at`` epoch seconds when the provider named when its limit lifts, + ``usage_limit`` on a usage-window plan's limit). */
export interface ErrorSurface {
layer: string
code: string
retryable: boolean
provider?: string | null
model?: string | null
resets_at?: number | null
usage_limit?: UsageLimit | null
[key: string]: unknown
}
/** ``agent/plan_limits.py::LimitHit`` — a usage-window plan's limit: what ran out, when it resets, and the one-click ways on (switch to a recommended model, use / add credits). */
export interface UsageLimit {
gauge_id: string
scope: string
limit_name: string
resets_at_ms?: number | null
message: string
suggestions?: UsageLimitSuggestion[]
credits?: UsageLimitCredits | null
current_model?: string
}
/** ``agent/plan_limits.py::ModelSuggestion`` — a recommended model that still works past the limit. */
export interface UsageLimitSuggestion {
model: string
label: string
note: string
provider?: string
}
/** ``agent/plan_limits.py::CreditsOption`` — ``use_credits`` (turn on Keep going), ``add_credits``, or ``add_credits_and_keep_going`` (both: Keep going is off and there is no balance). */
export interface UsageLimitCredits {
action: string
}
/** Committed SQLite row addresses for the agent's current-turn suffix. Missing ids are unproven, never negative acknowledgements. ``complete`` permits retiring the whole local turn only when the original turn boundary, every row and final body are still accounted for; compaction, redirects and partial writes conservatively leave it false. Row ids are scoped to the owning profile's store, as in ``SessionMessage.row_id``. */
export interface PersistedTurn {
row_ids: number[]
complete: boolean
user_row_id?: number | null
final_assistant_row_id?: number | null
user_row_ids?: number[] | null
submission_id?: string | null
}
/** ``server._status_update`` and the direct emitters (goal / loop / heartbeat / process). */
export interface StatusUpdatePayload {
kind: string
text: string
}
/** ``usage``: the status-bar view (``server._get_usage``), sent by the embedded backend's ticker (``server._start_usage_ticker``) and by a canonical local viewer's gateway after every API call and at turn end (``gateway/session_usage.py::usage_frame``). Read this. Deprecated: the top-level session-cumulative counters (``usage_stats``, the ``session.stats`` dict) that the gateway frame also carries. They are kept for existing readers; new readers use ``usage``, or ``session.stats`` for the raw counters. The embedded ticker never sends them. */
export interface SessionUsagePayload {
usage?: Usage | null
input_tokens?: number | null
output_tokens?: number | null
cache_read_tokens?: number | null
cache_write_tokens?: number | null
prompt_tokens?: number | null
completion_tokens?: number | null
total_tokens?: number | null
reasoning_tokens?: number | null
api_calls?: number | null
last_prompt_tokens?: number | null
context_tokens?: number | null
context_length?: number | null
config_context_length?: number | null
context_source?: string | null
compression_count?: number | null
avg_latency_s?: number | null
tokens_per_s?: number | null
last_turn_tokens?: number | null
rate_limit?: Record<string, unknown> | null
active_subagents?: number | null
model?: string | null
provider?: string | null
fallback_model?: string | null
plan_gauge?: PlanGauge | null
}
/** ``prompt_turn._invoke_agent`` ``_on_session_title`` hook. */
export interface SessionTitlePayload {
session_id: string
title: string
}
/** ``agent_callbacks`` reaction_callback. */
export interface ReactionPayload {
kind: string
}
/** ``server`` background_review_callback. */
export interface ReviewSummaryPayload {
text: string
}
/** A session-authority local-viewer turn: one line the agent printed through ``_print_fn`` (subagent completion, compaction, errors, budget notices), which main's classic CLI rendered through ``_agent_status_print``. */
export interface AgentPrintPayload {
text: string
}
/** ``tool_progress._on_tool_start`` (+ ``agent_callbacks._mirror_subagent_to_child`` rows with ``preview`` and empty ``args``). ``todos``/``revision`` are NOT set by the emitter; kept optional because tool.start rows may pass through connector redaction unchanged. */
export interface ToolStartPayload {
tool_id: string
name: string
context?: string | null
args?: Record<string, unknown> | null
args_text?: string | null
preview?: string | null
labels?: ToolLabel[] | null
}
/** ``tool_progress._on_tool_complete``; ``todos``/``revision`` merged in for the todo tools. */
export interface ToolCompletePayload {
tool_id: string
name: string
args?: Record<string, unknown> | null
duration_s?: number | null
result?: unknown
summary?: string | null
result_text?: string | null
inline_diff?: string | null
todos?: unknown[] | null
revision?: number | null
labels?: ToolLabel[] | null
}
/** ``agent_callbacks`` tool_gen_callback. */
export interface ToolGeneratingPayload {
name: string
}
/** ``tool_progress._progress_output_risk``. */
export interface ToolOutputRiskPayload {
tool_id: string
name: string
risk: string
findings: string[]
redacted: boolean
}
/** ``agent.tool_progress_relay.tool_progress_payload`` — an MCP server's ``notifications/progress`` for a running call, throttled to one per 500 ms per call. */
export interface ToolProgressPayload {
tool_id: string
name: string
progress: number
total?: number | null
percent?: number | null
message?: string | null
}
/** ``tool_progress._normalize_todo_state`` — full task snapshot. */
export interface TodoUpdatedPayload {
todos: unknown[]
revision: number
}
/** ``agent/credits_tracker.py::AgentNotice`` via notice_callback, and ``server._await_agent_ready``'s slow-build notice. ``level``: info | warn | error | success; ``kind``: sticky | ttl | agent. ``detail``: the full text behind a short ``text`` (the low-disk auto-prune question): Desktop shows it in the toast's expandable body, the Ink TUI prints it into the transcript. */
export interface NotificationShowPayload {
text: string
level: string
kind: string
ttl_ms?: number | null
key?: string | null
id?: string | null
detail?: string | null
}
export interface NotificationClearPayload {
key: string
}
/** ``tools/tip_tool.py``. */
export interface TipShowPayload {
selector: string
text: string
title?: string | null
side?: string | null
}
/** ``server._hydrate_resume_history``. */
export interface SessionResumeProgressPayload {
phase: string
status: ResumePhaseStatus
message_count?: number | null
message?: string | null
}
export type ResumePhaseStatus = 'loading' | 'complete' | 'failed'
/** ``session_lifecycle._announce_session_reclaimed`` (broadcast). */
export interface SessionReclaimedPayload {
session_id: string
stored_session_id: string
reason: string
}
/** ``session_lifecycle._announce_cancelled_gateway_approvals`` (broadcast). One frame for every pending approval dropped by an interrupt / reap / teardown (#106678) — the deny-resolve is silent without it, so a reconnecting client's prompt looks lost rather than cancelled. ``cancelled_count`` is the number of dropped entries; ``request_ids`` omits empty/missing ids, so the two can disagree when an entry has no request_id. */
export interface ApprovalCancelledPayload {
session_id: string
stored_session_id: string
reason: string
cancelled_count: number
request_ids: string[]
}
export interface SessionControlUpdatePayload {
control: SessionControlSnapshot
}
/** ``methods_session`` billing.step_up on_verification. */
export interface BillingStepUpVerificationPayload {
verification_url: string
user_code: string
}
/** ``methods_prompt._spawn_side_agent``: ``{task_id, **extra, text}``; btw adds ``question``. */
export interface SideAgentCompletePayload {
task_id: string
text: string
question?: string | null
}
/** ``methods_prompt`` restart body + ``agent_callbacks._preview_restart_callbacks``. */
export interface PreviewRestartProgressPayload {
task_id: string
text: string
level?: string | null
}
/** ``tool_progress._progress_subagent`` — every ``subagent.*`` frame; identity fields are optional because older emitters omit them and the TUI spawn tree falls back to flat rendering. */
export interface SubagentEventPayload {
goal: string
task_count: number
task_index: number
subagent_id?: string | null
parent_id?: string | null
child_session_id?: string | null
delegation_id?: string | null
depth?: number | null
model?: string | null
tool_count?: number | null
toolsets?: string[] | null
input_tokens?: number | null
output_tokens?: number | null
reasoning_tokens?: number | null
api_calls?: number | null
files_read?: string[] | null
files_written?: string[] | null
output_tail?: SubagentOutputTailEntry[] | null
tool_name?: string | null
text?: string | null
status?: SubagentStatus | null
summary?: string | null
duration_seconds?: number | null
tool_preview?: string | null
}
/** ``tools/delegate_tool_results.py::_extract_output_tail`` row. */
export interface SubagentOutputTailEntry {
tool: string
preview: string
is_error: boolean
}
/** ``tool_progress._progress_moa_reference``. */
export interface MoaReferencePayload {
label: string
text: string
index?: number | null
count?: number | null
}
export interface MoaAggregatingPayload {
aggregator: string
}
export interface MoaProgressPayload {
label: string
refs_done: number
refs_total: number
}
export interface MoaPhasePayload {
phase: string
refs_done?: number | null
refs_total?: number | null
aggregator?: string | null
}
/** ``tools/open_preview_tool.py``. */
export interface PreviewOpenPayload {
url: string
label?: string
}
/** ``tools/preview_tool.py`` / ``tools/close_preview_tool.py``; ``url`` '' closes every tab. */
export interface PreviewClosePayload {
url?: string
}
/** ``tools/focus_pane_tool.py``. */
export interface PaneRevealPayload {
pane: string
[key: string]: unknown
}
/** ``tools/react_to_message_tool.py``. */
export interface MessageReactionPayload {
row_id: number
reactions: MessageReaction[]
role: string
}
/** ``session_notifications`` process_registry.on_output. */
export interface TerminalOutputPayload {
process_id: string
chunk: string
}
export interface TerminalClosePayload {
process_id: string
}
/** ``methods_browser`` announce(); ``level``: info | warn | error. */
export interface BrowserProgressPayload {
message: string
level: string
}
/** ``methods_voice._vr_on_status``; states come from the recorder (idle / listening / transcribing …). */
export interface VoiceStatusPayload {
state: string
}
/** ``methods_voice`` voice.record ``on_partial`` — live STT text so far (``stt.streaming``). */
export interface VoicePartialPayload {
text: string
}
/** ``methods_voice._vr_transcript`` / ``_deliver_fd_transcript`` / typed stop phrase in methods_prompt. */
export interface VoiceTranscriptPayload {
text?: string | null
stop_phrase?: boolean | null
typed?: boolean | null
no_speech_limit?: boolean | null
}
/** ``methods_voice`` wake detector ``_on_detect``. */
export interface WakeDetectedPayload {
phrase: string
profile?: string | null
start_new_session: boolean
}
/** ``change_watcher._pet_changed_payload`` — ``pet.info.meta``-shaped; ``{enabled: false}`` when off. */
export interface PetChangedPayload {
enabled: boolean
slug?: string | null
displayName?: string | null
scale?: number | null
spritesheetRevision?: string | null
[key: string]: unknown
}
/** ``methods_session`` pet.generate: token-only init frame, then one per draft. */
export interface PetGenerateProgressPayload {
token: string
count: number
index?: number | null
dataUri?: string | null
[key: string]: unknown
}
/** ``methods_session`` pet.hatch ``_on_progress``: ``{event, detail}`` or the parsed row form. */
export interface PetHatchProgressPayload {
event: string
detail?: string | null
state?: string | null
done?: string | null
total?: string | null
[key: string]: unknown
}
/** ``change_watcher._CHANGE_WATCHES`` payload fn — ``{}`` for every watch except pet.changed. */
export type ChangeSignalPayload = Record<string, unknown>
export type ConnectorErrorReason = 'INVALID_PARAMS' | 'NOT_OWNER' | 'UNSUPPORTED_RUNTIME' | 'CONNECTOR_REQUEST_FAILED' | 'INVALID_CONNECTOR_RESPONSE' | 'UNKNOWN_TARGET' | 'LINK_STILL_VALID' | 'REISSUE_REFUSED' | 'UNKNOWN_OPERATION' | 'INVALID_ANSWER' | 'NEEDS_NOUS_AUTH' | 'CONNECTOR_NOT_FOUND' | 'TOOLS_UNAVAILABLE' | 'CONNECTORS_UNAVAILABLE' | 'CATALOG_UNAVAILABLE' | 'ACCOUNTS_UNAVAILABLE' | 'CONNECTION_NOT_FOUND' | 'POLICY_UNAVAILABLE' | 'POLICY_CONFLICT' | 'FORBIDDEN_SCOPE' | 'ORG_REQUIRED' | 'ORG_ACCESS_DENIED' | 'INVALID_POLICY' | 'ALIAS_TAKEN'
// ── Client→server methods ──
export interface RpcMethods {
/** Registry-wide background process summary for ``/agents``. */
'agents.list': { params: AgentsListParams; result: AgentsListResult }
/** Replay the approvals still waiting on this session (reconnect / polling). */
'approval.pending': { params: ApprovalPendingParams; result: ApprovalPendingResult }
/** Tell the backend the card is on screen, so its timeout clock starts. */
'approval.received': { params: ApprovalReceivedParams; result: ApprovalReceivedResult }
/** Deliver the user's decision on a dangerous command (falls back to durable identity on a stale sid). */
'approval.respond': { params: ApprovalRespondParams; result: ApprovalRespondResult }
/** Enable/disable auto top-up with its threshold and reload amount (billing:manage). */
'billing.auto_reload': { params: BillingAutoReloadParams; result: BillingMutationResult }
/** Start a one-off top-up charge (billing:manage, idempotent). */
'billing.charge': { params: BillingChargeParams; result: BillingChargeResult }
/** Poll one charge by id. */
'billing.charge_status': { params: BillingChargeStatusParams; result: BillingChargeStatusResult }
/** Window plans: turn 'Keep going on credits' on/off (billing:manage). */
'billing.keep_going_on_credits': { params: BillingKeepGoingOnCreditsParams; result: BillingMutationResult }
/** Read-only billing view (no scope); the Nous free tier is answered locally without a portal call. */
'billing.state': { params: ProfileParams; result: BillingStateResult }
/** Run the billing:manage device flow; the URL/code arrive via billing.step_up.verification. */
'billing.step_up': { params: BillingStepUpParams; result: BillingStepUpResult }
/** Deliver a relayed DM into a Bot Chat on this gateway and return the one-turn reply (blocking). */
'bot_relay.deliver': { params: BotRelayDeliverParams; result: BotRelayDeliverResult }
/** Atomically claim every pending cross-connection envelope queued on this gateway. */
'bot_relay.outbox.drain': { params: BotRelayOutboxDrainParams; result: BotRelayOutboxDrainResult }
/** Write a relayed reply and/or typed error for an envelope so the sender-side waiter resolves. */
'bot_relay.reply': { params: BotRelayReplyParams; result: OkResult }
/** Replace this gateway's view of agents on other connections; answers the accepted row count. */
'bot_relay.roster.sync': { params: BotRelayRosterSyncParams; result: BotRelayRosterSyncResult }
/** Inspect, attach to, or drop the CDP browser the tools use; ``messages`` narrate a connect. */
'browser.manage': { params: BrowserManageParams; result: BrowserManageResult }
/** Lock one answer of a batch clarify request (editable until every question is locked). */
'clarify.lock': { params: ClarifyLockParams; result: ClarifyLockResult }
/** Run ``hermes <argv>`` non-interactively and capture its output; ``blocked`` explains a refusal. */
'cli.exec': { params: CliExecParams; result: CliExecResult }
/** What the calling client handles, sent once per connection (after gateway.ready); returns the server→client request methods this backend may send. */
'client.capabilities': { params: ClientCapabilitiesParams; result: ClientCapabilitiesResult }
/** Save the host clipboard image into the session and queue it for the next turn. */
'clipboard.paste': { params: ClipboardPasteParams; result: AttachedImageResult }
/** Run a quick/plugin/bundle/skill/built-in slash command and answer a structured directive. */
'command.dispatch': { params: CommandDispatchParams; result: CommandDispatchResult }
/** Canonical registry command for a name or alias. */
'command.resolve': { params: CommandResolveParams; result: CommandResolveResult }
/** Categorized slash metadata (registry, quick, plugin, skill) for completion menus. */
'commands.catalog': { params: CommandsCatalogParams; result: CommandsCatalogResult }
/** Path / @-reference completions for the composer (files, folders, profiles, plugin providers). */
'complete.path': { params: CompletePathParams; result: CompletionItemsResult }
/** Ranked slash-command / skill completions for a ``/`` token. */
'complete.slash': { params: CompleteSlashParams; result: CompleteSlashResult }
/** Read one normalised config value (or the whole effective config) the way the UIs render it. */
'config.get': { params: ConfigGetParams; result: ConfigGetResult }
/** Change one config key (persisted or session-scoped) and read back the normalised value. */
'config.set': { params: ConfigSetParams; result: ConfigSetResult }
/** Masked, display-ready config summary (model / agent / environment rows). */
'config.show': { params: ConfigShowParams; result: ConfigShowResult }
/** Per-target outcomes from the card, and an optional Continue. */
'connection.respond': { params: ConnectionRespondParams; result: ConnectionRespondResult }
/** The scoped member's hosted connector accounts, optionally filtered by connector slug. */
'connectors.accounts': { params: ConnectorAccountsParams; result: ConnectorAccountsResult }
/** Remove one hosted connector account owned by the scoped member. */
'connectors.accounts.remove': { params: ConnectorAccountsRemoveParams; result: ConnectorAccountsRemoveResult }
/** Name or rename one hosted connector account owned by the scoped member. */
'connectors.accounts.rename': { params: ConnectorAccountsRenameParams; result: ConnectorAccountRow }
/** The hosted connector catalog available to the scoped member. */
'connectors.catalog': { params: ProfileParams; result: ConnectorsCatalogResult }
/** Start or re-initiate authorization for named connectors on a session or account operation. */
'connectors.connect': { params: ConnectorsConnectParams; result: ConnectorsConnectResult }
/** Connector catalog + connection state for one session or profile account owner. */
'connectors.list': { params: ConnectorsListParams; result: ConnectorsListResult }
/** The current snapshot of one open session or account operation. */
'connectors.operation.status': { params: ConnectionOperationParams; result: ConnectionOperationStatus }
/** The browser leg came back (hermes://connections/done): read the accounts now, not at the next tick. */
'connectors.operation.wake': { params: ConnectionOperationParams; result: ConnectionWakeResult }
/** Policy layers for the scoped member, from organization to member scope. */
'connectors.policy.get': { params: ProfileParams; result: ConnectorPolicyGetResult }
/** Apply one scoped member connector or tool-list policy change. */
'connectors.policy.set': { params: ConnectorPolicySetParams; result: ConnectorPolicySetResult }
/** The scoped profile's cached or current tool list for one connector. */
'connectors.tools': { params: ConnectorToolsParams; result: ConnectorToolsResult }
/** List/add/remove/pause/resume cron jobs in the (optionally profile-scoped) cron store. */
'cron.manage': { params: CronManageParams; result: CronManageResult }
/** Block/unblock NEW spawns globally (active children keep running); returns the new state. */
'delegation.pause': { params: DelegationPauseParams; result: DelegationPauseResult }
/** Running subagent tree plus the spawn pause flag and limits. */
'delegation.status': { params: ProfileParams; result: DelegationStatusResult }
/** Upload a force-redacted debug bundle to Nous-internal diagnostics storage. */
'diagnostics.share_nous': { params: DiagnosticsShareNousParams; result: DiagnosticsShareNousResult }
/** Run the distro package install on the gateway host; progress streams as display.install.log/.done. */
'display.install': { params: ProfileParams; result: DisplayInstallResult }
/** Take over: the human named by a viewer id this connection minted controls the screen. */
'display.lease.acquire': { params: DisplayLeaseAcquireParams; result: DisplayLeaseResult }
/** Hand back. Without a viewer id the release is refused while a human holds unless force. */
'display.lease.release': { params: DisplayLeaseReleaseParams; result: DisplayLeaseResult }
/** Mint a single-use ticket for /api/display/ws and the server-minted viewer id for this connection. */
'display.observe': { params: DisplayObserveParams; result: DisplayObserveResult }
/** Start this profile's Xvnc + Xfce (idempotent); blocks until the display is published. */
'display.start': { params: ProfileParams; result: DisplayStatus }
/** Runtime + lease snapshot for this profile's screen. */
'display.status': { params: ProfileParams; result: DisplayStatus }
/** Stop the screen. Refused (5300, code viewer_mismatch) while a human holds unless force. */
'display.stop': { params: DisplayStopParams; result: DisplayStopResult }
/** Decide the pending default sandbox image switch for this profile; refused when none is pending. */
'display.switchSandboxImage': { params: DisplaySwitchSandboxImageParams; result: DisplaySwitchSandboxImageResult }
/** One JPEG grab of the bot's screen; read-only, never changes the lease. */
'display.thumbnail': { params: ProfileParams; result: DisplayThumbnailResult }
/** Stage a non-image file into the session workspace and hand back its @file: ref. */
'file.attach': { params: FileAttachParams; result: FileAttachResult }
/** Mark the one-time availability notice as shown on the free-tier identity. */
'free_tier.ack_notice': { params: ProfileParams; result: FreeTierAckNoticeResult }
/** Report a browser window outcome for the matching pending attempt; mint remains authoritative. */
'free_tier.challenge_result': { params: FreeTierChallengeResultParams; result: FreeTierChallengeResult }
/** Claim the due sign-in offer; true for exactly one caller each time an offer comes due. */
'free_tier.claim_nudge': { params: FreeTierClaimNudgeParams; result: FreeTierClaimNudgeResult }
/** Explicit retry of the free-tier identity mint when the boot bootstrap could not create it. */
'free_tier.provision': { params: ProfileParams; result: FreeTierProvisionResult }
/** Pure read of the focused profile's free-tier identity state (no network, no side effects). */
'free_tier.status': { params: ProfileParams; result: FreeTierStatusResult }
/** What THIS build enforces (a client withholds a feature unless advertised). */
'gateway.capabilities': { params: PingParams; result: GatewayCapabilitiesResult }
/** Resolve one exact pending approval raised by a local or peer room member. */
'groups.approve': { params: GroupsApproveParams; result: GroupsApproveResult }
/** Read one committed attachment for a live room viewer. */
'groups.attachment.download': { params: GroupsAttachmentDownloadParams; result: RoomAttachmentBytes }
/** Store one attachment for a later groups.send manifest (idempotent per upload_id). */
'groups.attachment.upload': { params: GroupsAttachmentUploadParams; result: RoomAttachment }
/** Describe the hosted-room protocol implemented by this gateway. */
'groups.capabilities': { params: GroupsCapabilitiesParams; result: GroupsCapabilitiesResult }
/** Create a hosted room idempotently; authority is this gateway's stable install identity. */
'groups.create': { params: GroupsCreateParams; result: GroupsCreateResult }
/** Fence this gateway's stale room authority against a proven newer epoch. */
'groups.demote': { params: GroupsDemoteParams; result: GroupsDemoteResult }
/** Permanently tombstone a hosted room id after stopping its work and revoking peer routes. */
'groups.disband': { params: GroupsDisbandParams; result: GroupsDisbandResult }
/** Discard one indeterminate room task after explicit user confirmation. */
'groups.discard': { params: GroupsDiscardParams; result: GroupsDiscardResult }
/** List rooms hosted by this gateway, most recently changed first. */
'groups.list': { params: GroupsListParams; result: GroupsListResult }
/** A monotonic room-log delta after since_seq, bounded by count and page bytes. */
'groups.log': { params: GroupsLogParams; result: GroupsLogResult }
/** Mint one target-issued room/profile grant for a prospective room home. */
'groups.peer.invite': { params: GroupsPeerInviteParams; result: GroupsPeerInviteResult }
/** Register and probe one scoped peer route on the room home. */
'groups.peer.register': { params: GroupsPeerRegisterParams; result: GroupsPeerRegisterResult }
/** Revoke one target-issued grant using its exact profile scope. */
'groups.peer.revoke': { params: GroupsPeerRevokeParams; result: GroupsPeerRevokeResult }
/** Continue a replicated room on this gateway at epoch + 1; requires confirm=true. */
'groups.promote': { params: GroupsPromoteParams; result: GroupsPromoteResult }
/** Rename one hosted room atomically with its replay event. */
'groups.rename': { params: GroupsRenameParams; result: GroupsRenameResult }
/** The local replica's coverage and authority lineage for one room. */
'groups.replica_state': { params: GroupsReplicaStateParams; result: GroupsReplicaStateResult }
/** Persist one authority-stamped replay page into the local replica store; idempotent. */
'groups.replicate': { params: GroupsReplicateParams; result: GroupsReplicateResult }
/** Retry one indeterminate room task after explicit user confirmation. */
'groups.retry': { params: GroupsRetryParams; result: GroupsRetryResult }
/** Append one inert message.user event idempotently; the actor is server-owned. */
'groups.send': { params: GroupsSendParams; result: GroupsSendResult }
/** One hosted room's replay cursor and fenced authority state, plus live driver status. */
'groups.state': { params: GroupsStateParams; result: GroupsStateResult }
/** Durably cancel queued or running work for one hosted room. */
'groups.stop': { params: GroupsStopParams; result: GroupsStopResult }
/** Fail a not-yet-claimed handoff (client poll timeout); CAS against the watcher. */
'handoff.fail': { params: HandoffFailParams; result: HandoffFailResult }
/** Queue a handoff to a messaging platform's home channel; the gateway watcher claims it. */
'handoff.request': { params: HandoffRequestParams; result: HandoffRequestResult }
/** Poll the handoff row for this session. */
'handoff.state': { params: SessionParams; result: HandoffStateResult }
/** Pack + overlay messages for one language and surface; the renderer merges them over its bundled catalog. */
'i18n.catalog': { params: I18nCatalogParams; result: I18nCatalogResult }
/** Every language some layer supplies (bundled ∪ user overlay ∪ plugin packs), en first. */
'i18n.languages': { params: ProfileParams; result: I18nLanguagesResult }
/** Queue a gateway-visible image file for the next turn. */
'image.attach': { params: ImageAttachParams; result: AttachedImageResult }
/** Queue an image uploaded as base64 (remote client); reply mirrors image.attach. */
'image.attach_bytes': { params: ImageAttachBytesParams; result: AttachedImageResult }
/** Drop a queued image before the turn is sent. */
'image.detach': { params: ImageDetachParams; result: ImageDetachResult }
/** Generate an image through the tool's provider dispatcher and hand the renderer a data URL. */
'image.generate': { params: ImageGenerateParams; result: ImageGenerateResult }
/** Recognise a terminal file drop pasted into the composer and turn it into an attachment. */
'input.detect_drop': { params: InputDetectDropParams; result: InputDetectDropResult }
/** Session/message counts over the last ``days`` for the (optionally scoped) profile store. */
'insights.get': { params: InsightsGetParams; result: InsightsGetResult }
/** Archive a skill (restorable via curator) or remove a memory chunk. */
'learning.delete': { params: LearningNodeParams; result: LearningMutationResult }
/** Node content (SKILL.md or memory chunk) for an edit prefill. */
'learning.detail': { params: LearningNodeParams; result: LearningDetailResult }
/** Rewrite a node's content (SKILL.md or memory chunk). */
'learning.edit': { params: LearningEditParams; result: LearningMutationResult }
/** Pre-render the /journey timeline (frames + legend/summary) so the TUI walks it locally. */
'learning.frames': { params: LearningFramesParams; result: LearningFramesResult }
/** Stateless one-shot LLM completion (titles, ideas) on the session's or the task backend. */
'llm.oneshot': { params: LlmOneshotParams; result: LlmOneshotResult }
/** Facts about the machine running this backend and its OS account, for the desktop first run. */
'machine.facts': { params: Params; result: MachineFactsResult }
/** Curated MCP presets with per-profile installed/enabled state and the env keys each needs. */
'mcp.catalog': { params: ProfileParams; result: McpCatalogResult }
/** Add a server to the profile's config from a catalog preset and/or an explicit config. */
'mcp.servers.add': { params: McpServersAddParams; result: McpServersAddResult }
/** Configured MCP servers for the (scoped) profile, secrets redacted to env-key names. */
'mcp.servers.list': { params: ProfileParams; result: McpServersListResult }
/** Relay a client-captured redirect into a client_redirect_uri flow. */
'mcp.servers.oauth.callback': { params: McpOauthCallbackParams; result: McpOauthCallbackResult }
/** Cancel a flow owned by the resolved profile, waking its callback worker. */
'mcp.servers.oauth.cancel': { params: McpOauthFlowParams; result: McpOauthCancelResult }
/** Poll a flow; approved persists tokens for the profile and returns the probed tools. */
'mcp.servers.oauth.poll': { params: McpOauthFlowParams; result: McpOauthPollResult }
/** Begin a PKCE OAuth flow; the client opens auth_url and polls mcp.servers.oauth.poll. */
'mcp.servers.oauth.start': { params: McpOauthStartParams; result: McpOauthStartResult }
/** Drop a server from the profile's config.yaml. */
'mcp.servers.remove': { params: McpServerNameParams; result: McpServersRemoveResult }
/** Store a credential in the profile's .env and reference it from the server config (header or env). */
'mcp.servers.set_api_key': { params: McpServersSetApiKeyParams; result: McpServersSetApiKeyResult }
/** Cached runtime state per configured server; never connects, probes, or starts auth. */
'mcp.servers.status': { params: ProfileParams; result: McpServersStatusResult }
/** Connect, list tools, disconnect — an OAuth server with no token on disk is reported as not ok. */
'mcp.servers.test': { params: McpServerNameParams; result: McpServersTestResult }
/** Set/clear one author's emoji reaction on a message; returns the row's full reaction list. */
'message.react': { params: MessageReactParams; result: MessageReactResult }
/** Remove every credential (env keys and OAuth state) for a provider. */
'model.disconnect': { params: ModelDisconnectParams; result: ModelDisconnectResult }
/** Provider/model inventory for the picker, layered over the session's live provider when given. */
'model.options': { params: ModelOptionsParams; result: ModelOptionsResult }
/** Save an API key for a provider and return its refreshed inventory row. */
'model.save_key': { params: ModelSaveKeyParams; result: ModelSaveKeyResult }
/** Write onboarding.run in the root profile's config.yaml; answers the new state. */
'onboarding.set_run': { params: OnboardingSetRunParams; result: OnboardingRunStateResult }
/** Skip setup: end the session's onboarding run and close the card that waits. */
'onboarding.skip': { params: OnboardingSkipParams; result: OnboardingSkipResult }
/** Open the onboarding chat in the default profile: create it, write its run record and play the opening. */
'onboarding.start': { params: OnboardingStartParams; result: OnboardingStartResult }
/** Whether desktop first-run onboarding is due, and the chat in progress; reads the root profile's config. */
'onboarding.state': { params: OnboardingStateParams; result: OnboardingRunStateResult }
/** Spill a large paste to a file and hand back the inline placeholder. */
'paste.collapse': { params: PasteCollapseParams; result: PasteCollapseResult }
/** Render a PDF's pages to PNG and queue them as images for the next turn. */
'pdf.attach': { params: PdfAttachParams; result: PdfAttachResult }
/** Stop an in-flight pet generate/hatch by token (idempotent). */
'pet.cancel': { params: PetCancelParams; result: PetCancelResult }
/** Half-block cell frames (or a kitty placement) for one pet state. */
'pet.cells': { params: PetCellsParams; result: PetCellsResult }
/** Turn the pet display off from the desktop picker. */
'pet.disable': { params: ProfileParams; result: OkResult }
/** Export an installed pet as a re-importable .zip. */
'pet.export': { params: PetSlugParams; result: PetExportResult }
/** Petdex gallery + local install state (installed-only offline); localOnly skips the remote manifest. */
'pet.gallery': { params: PetGalleryParams; result: PetGalleryResult }
/** Candidate base looks for a new pet (draft step); drafts also stream via pet.generate.progress. */
'pet.generate': { params: PetGenerateParams; result: PetGenerateResult }
/** Whether pet generation is possible (a reference-capable image backend) and which providers. */
'pet.generate.status': { params: ProfileParams; result: PetGenerateStatusResult }
/** Turn a base draft into a full spritesheet pet; progress streams via pet.hatch.progress. */
'pet.hatch': { params: PetHatchParams; result: PetHatchResult }
/** Active pet for sprite renderers: spritesheet (base64) + frame geometry + state-row taxonomy. */
'pet.info': { params: PetInfoParams; result: PetInfoResult }
/** Cheap active-pet metadata used to avoid full payload refreshes. */
'pet.info.meta': { params: ProfileParams; result: PetInfoMetaResult }
/** Uninstall a pet (delete its directory); if it was active, turn the display off. */
'pet.remove': { params: PetSlugParams; result: PetSlugResult }
/** Rename a pet's display name + realign its slug/dir; follows the active slug in config. */
'pet.rename': { params: PetRenameParams; result: PetSlugResult }
/** Persist display.pet.scale (clamped to engine bounds) from the desktop slider. */
'pet.scale': { params: PetScaleParams; result: PetScaleResult }
/** Adopt a pet: install (if needed) + activate; writes display.pet.* to config. */
'pet.select': { params: PetSlugParams; result: PetSlugResult }
/** Idle-frame PNG data URI for the picker (desktop CSP breaks CDN <img>). */
'pet.thumb': { params: PetThumbParams; result: PetThumbResult }
/** Cheapest liveness probe; answered on the WS reader thread even while every agent is mid-turn. */
ping: { params: PingParams; result: PingResult }
/** One curated plugin-catalog entry by name, from the backend's live catalog (cached, with the in-tree fallback and kill list); backs hermes://plugin/install?catalog= deep links. */
'plugins.catalog.lookup': { params: PluginCatalogLookupParams; result: PluginCatalogLookupResult }
/** Loaded plugin manager entries (legacy flat view); the Plugins Hub uses plugins.manage list. */
'plugins.list': { params: PluginsListParams; result: PluginsListResult }
/** Plugins Hub backend: list installed plugins, toggle, git-install, re-pin a catalog install, or remove a user install. */
'plugins.manage': { params: PluginsManageParams; result: PluginsManageResult }
/** Spawn a hidden agent that brings the desktop preview's dev server back up. */
'preview.restart': { params: PreviewRestartParams; result: TaskIdResult }
/** Kill one background process the caller's session owns and return its output snapshot. */
'process.kill': { params: ProcessKillParams; result: ProcessKillResult }
/** Background processes owned by the caller's session (desktop status stack poll). */
'process.list': { params: ProcessListParams; result: ProcessListResult }
/** ``/stop``: on the shared owner, kill the background processes ``session_id`` owns (required); a standalone sidecar kills every process it holds. Answers the count killed. */
'process.stop': { params: ProcessStopParams; result: ProcessStopResult }
/** Editor Save: apply any subset of a profile's sections and report each one. */
'profiles.configure': { params: ProfilesConfigureParams; result: ProfilesConfigureResult }
/** Create a profile (ws twin of POST /api/profiles), mirroring launch credentials by default. */
'profiles.create': { params: ProfilesCreateParams; result: ProfilesCreateResult }
/** Everything the profile editor shows: soul, model pin, skills, toolsets, MCP servers. */
'profiles.describe': { params: ProfileNameParams; result: ProfilesDescribeResult }
/** A profile asset as a data URL. */
'profiles.get_asset': { params: ProfilesGetAssetParams; result: ProfilesGetAssetResult }
/** Roster of profiles with previews so a client paints without N follow-up calls. */
'profiles.list': { params: ProfilesListParams; result: ProfilesListResult }
/** Store or clear a profile asset (avatar) atomically. */
'profiles.set_asset': { params: ProfilesSetAssetParams; result: ProfilesSetAssetResult }
/** Structured project facts for a cwd so UIs don't re-sniff the workspace. */
'project.facts': { params: ProjectFactsParams; result: ProjectFactsResult }
/** Attach a folder to a project (optionally as its primary path). */
'projects.add_folder': { params: ProjectsAddFolderParams; result: ProjectResult }
/** Archive (or with ``restore`` un-archive) a project; answers the full listing. */
'projects.archive': { params: ProjectsArchiveParams; result: ProjectsPayload }
/** Create a project from a name + folders; duplicate primary paths are refused (5063). */
'projects.create': { params: ProjectsCreateParams; result: OptionalProjectResult }
/** Delete a project and its folders; answers the full listing. */
'projects.delete': { params: ProjectIdParams; result: ProjectsPayload }
/** Repos for the desktop overview: scanned-from-disk (cached) ∪ session-derived. */
'projects.discover_repos': { params: ProjectsDiscoverReposParams; result: ProjectsDiscoverReposResult }
/** Which project (if any) owns a directory, plus the resolved cwd and its git branch. */
'projects.for_cwd': { params: ProjectsForCwdParams; result: ProjectsForCwdResult }
/** One stored project with its folders. */
'projects.get': { params: ProjectIdParams; result: ProjectResult }
/** Every project of the profile (archived included) plus which one is active. */
'projects.list': { params: ProfileParams; result: ProjectsPayload }
/** Fully hydrated lanes for one project, from the same grouping as projects.tree. */
'projects.project_sessions': { params: ProjectsProjectSessionsParams; result: ProjectsProjectSessionsResult }
/** Persist repo roots found by the client's (desktop-side) scan; return the merged list. */
'projects.record_repos': { params: ProjectsRecordReposParams; result: ProjectsRecordReposResult }
/** Detach a folder from a project. */
'projects.remove_folder': { params: ProjectFolderParams; result: ProjectResult }
/** Switch (or clear) the active project for the profile. */
'projects.set_active': { params: ProjectsSetActiveParams; result: ActiveIdResult }
/** Make one attached folder the project's primary path. */
'projects.set_primary': { params: ProjectFolderParams; result: ProjectResult }
/** Project → repo → lane overview with counts and a few preview sessions per project. */
'projects.tree': { params: ProjectsTreeParams; result: ProjectsTreeResult }
/** Patch a project's display fields; answers the refreshed project. */
'projects.update': { params: ProjectsUpdateParams; result: ProjectResult }
/** Run a task on a fresh agent in the background; the answer arrives as background.complete. */
'prompt.background': { params: SideAgentParams; result: TaskIdResult }
/** Side question over a snapshot of the live conversation; the answer arrives as btw.complete. */
'prompt.btw': { params: SideAgentParams; result: TaskIdResult }
/** Send a user turn to a live session; busy sessions queue / steer / redirect instead of refusing. */
'prompt.submit': { params: PromptSubmitParams; result: PromptSubmitResult }
/** Re-read ~/.hermes/.env (CLI /reload parity); built agents keep their pool until /new. */
'reload.env': { params: ReloadEnvParams; result: ReloadEnvResult }
/** Tear down and rediscover MCP servers for every live session (prompt cache is invalidated). */
'reload.mcp': { params: ReloadMcpParams; result: ReloadMcpResult }
/** Answer an open server→client request from a client that never received the frame. */
'request.answer': { params: RequestAnswerParams; result: RequestAnswerResult }
/** Diff between a checkpoint and the working tree, with an ANSI rendering sized to the TUI. */
'rollback.diff': { params: RollbackDiffParams; result: RollbackDiffResult }
/** Checkpoints for the session's cwd; ``enabled: false`` when checkpointing is off. */
'rollback.list': { params: RollbackListParams; result: RollbackListResult }
/** Restore the working tree (or one file) to a checkpoint by hash or 1-based index. */
'rollback.restore': { params: RollbackRestoreParams; result: RollbackRestoreResult }
/** Attach the frontend to a live session without closing the previously focused one. */
'session.activate': { params: SessionActivateParams; result: SessionActivateResult }
/** Live sessions in this process, insertion order (not a DB browser). */
'session.active_list': { params: SessionActiveListParams; result: SessionActiveListResult }
/** Set/clear archived (soft-hide, messages kept) on a session + lineage; Desktop PATCH parity. */
'session.archive': { params: SessionArchiveParams; result: SessionArchiveResult }
/** Fork a live session into a new stored child that shares the parent's history so far. */
'session.branch': { params: SessionBranchParams; result: SessionBranchResult }
/** Whole-session branch of a stored parent: the owning backend reads and copies the transcript, which never crosses the wire (a separate method so an older gateway fails loudly, not with an empty branch). */
'session.branch_stored': { params: SessionBranchStoredParams; result: SessionBranchStoredResult }
/** session.branch of the whole history without echoing the copied transcript back. */
'session.branch_whole': { params: SessionBranchWholeParams; result: SessionBranchWholeResult }
/** Tear down a live session (its stored row stays resumable). */
'session.close': { params: SessionCloseParams; result: SessionCloseResult }
/** Manual /compress of an idle session, optionally focused on a topic. */
'session.compress': { params: SessionCompressParams; result: SessionCompressResult }
/** Cursor-style split of the context window by category. */
'session.context_breakdown': { params: SessionContextBreakdownParams; result: SessionContextBreakdownResult }
/** Run one allowlisted goal / loop / subgoal / heartbeat action and return the exact resulting snapshot. */
'session.control': { params: SessionControlParams; result: SessionControlResult }
/** Stable, allowlisted snapshot of one live session's goal / loop / heartbeat state. */
'session.control.read': { params: SessionControlReadParams; result: SessionControlReadResult }
/** Mint a live session (agent builds after the reply); a DB row appears on the first prompt unless seeded. */
'session.create': { params: SessionCreateParams; result: SessionCreateResult }
/** Change a live, idle session's working directory. */
'session.cwd.set': { params: SessionCwdSetParams; result: SessionCwdSetResult }
/** Delete a stored session + transcripts; refused while it is live here. */
'session.delete': { params: SessionDeleteParams; result: SessionDeleteResult }
/** Replay events after a seq watermark on WS reconnect; truncated means refetch state. */
'session.events.since': { params: SessionEventsSinceParams; result: SessionEventsSinceResult }
/** Replay-buffer occupancy telemetry (ops/debug). */
'session.events.stats': { params: SessionEventsStatsParams; result: SessionEventsStatsResult }
/** Import a foreign session into this profile's history (idempotent per origin). */
'session.foreign.import': { params: SessionForeignIdParams; result: SessionForeignImportResult }
/** One page of Claude Code / Codex sessions found on the serving backend. */
'session.foreign.list': { params: SessionForeignListParams; result: SessionForeignListResult }
/** Preview a foreign session's tail before importing it. */
'session.foreign.preview': { params: SessionForeignIdParams; result: SessionForeignPreviewResult }
/** The durable display transcript (ancestors included, row ids attached). */
'session.history': { params: SessionHistoryParams; result: SessionHistoryResult }
/** Stop the running turn (and streaming TTS); retires the crash-recovery marker. */
'session.interrupt': { params: SessionInterruptParams; result: SessionInterruptResult }
/** Human-facing stored sessions, most recent first (sub-agent / kanban sources denied). */
'session.list': { params: SessionListParams; result: SessionListResult }
/** Most recent human-facing session; errors fold into a null session_id. */
'session.most_recent': { params: SessionMostRecentParams; result: SessionMostRecentResult }
/** Redirect the active turn (queued for the next turn while the agent is still building). */
'session.redirect': { params: SessionCorrectionParams; result: SessionCorrectionResult }
/** Attach to a stored session: reuse it if live here, else lazy / deferred / cold / eager rebuild. */
'session.resume': { params: SessionResumeParams; result: SessionResumeResult }
/** Export the transcript to ~/.hermes/sessions/saved (classic /save). */
'session.save': { params: SessionSaveParams; result: SessionSaveResult }
/** Set/clear hidden (out of the default list, still resumable by its owner) on a session + lineage. */
'session.set_hidden': { params: SessionSetHiddenParams; result: SessionSetHiddenResult }
/** Rendered /status text for the session. */
'session.status': { params: SessionStatusParams; result: SessionStatusResult }
/** Inject text into the next tool result without interrupting the turn. */
'session.steer': { params: SessionCorrectionParams; result: SessionCorrectionResult }
/** Read or set a live session's title; a title set before the row exists is queued. */
'session.title': { params: SessionTitleParams; result: SessionTitleResult }
/** Drop the last user turn (and everything after it) from an idle session. */
'session.undo': { params: SessionUndoParams; result: SessionUndoResult }
/** Token / context / cost counters for the session (+ Nous credit lines when available). */
'session.usage': { params: SessionUsageParams; result: SessionUsageResult }
/** Re-home a stored session's workspace; git identity is replaced and a live agent follows. */
'session.workspace.move': { params: SessionWorkspaceMoveParams; result: SessionWorkspaceMoveResult }
/** Strict provider check through the same runtime resolution the agent uses on session creation. */
'setup.runtime_check': { params: SetupRuntimeCheckParams; result: SetupRuntimeCheckResult }
/** Loose provider check: is ANY provider auth state discoverable for the (launch or named) profile. */
'setup.status': { params: ProfileParams; result: SetupStatusResult }
/** Record one finished Desktop day (mode use + button presses); recorded=false keeps it for a retry. */
'shared_metrics.desktop_daily': { params: SharedMetricsDesktopDailyParams; result: SharedMetricsDesktopDailyResult }
/** Count one Desktop dislike signal (fire-and-forget; capped per signal per day; a no-op unless on). */
'shared_metrics.desktop_dislike': { params: SharedMetricsDesktopDislikeParams; result: OkResult }
/** Count one Desktop area used today (fire-and-forget; once per area per UTC day; a no-op unless on). */
'shared_metrics.desktop_feature_use': { params: SharedMetricsDesktopFeatureUseParams; result: OkResult }
/** Count one Desktop friction event (fire-and-forget; capped per day; a no-op unless on). */
'shared_metrics.desktop_friction': { params: SharedMetricsDesktopFrictionParams; result: OkResult }
/** Count one Desktop first-run step transition (fire-and-forget; once per step+event; a no-op unless on). */
'shared_metrics.desktop_onboarding': { params: SharedMetricsDesktopOnboardingParams; result: OkResult }
/** Write both shared-metrics opt-ins at once (send requires collection) and reconcile consent windows. */
'shared_metrics.set': { params: SharedMetricsSetParams; result: SharedMetricsConsentResult }
/** Count one user-typed slash command (fire-and-forget; a no-op unless shared metrics are on). */
'shared_metrics.slash_command': { params: SharedMetricsSlashCommandParams; result: SharedMetricsSlashCommandResult }
/** Record one client launch-to-ready latency (fire-and-forget; a no-op unless shared metrics are on). */
'shared_metrics.startup_latency': { params: SharedMetricsStartupLatencyParams; result: SharedMetricsStartupLatencyResult }
/** Pure read of the focused profile's shared-metrics opt-ins (collection, upload, answered). */
'shared_metrics.status': { params: ProfileParams; result: SharedMetricsConsentResult }
/** Count one Desktop packaged self-update outcome (fire-and-forget; a no-op unless shared metrics are on). */
'shared_metrics.update_run': { params: SharedMetricsUpdateRunParams; result: SharedMetricsUpdateRunResult }
/** Run a safe (non-dangerous) shell command captured for ``!cmd`` / inline substitution. */
'shell.exec': { params: ShellExecParams; result: ShellExecResult }
/** Skills hub backend: list the profile's skills or search / browse / inspect / install from the hub. */
'skills.manage': { params: SkillsManageParams; result: SkillsManageResult }
/** Re-scan skill dirs; the pre-rendered ``output`` is what /reload-skills prints. */
'skills.reload': { params: SkillsReloadParams; result: SkillsReloadResult }
/** Execute a slash command against the session's slash worker (or a live/plugin shortcut). */
'slash.exec': { params: SlashExecParams; result: SlashExecResult }
/** Saved spawn-tree snapshots, newest first. */
'spawn_tree.list': { params: SpawnTreeListParams; result: SpawnTreeListResult }
/** Read one saved spawn-tree snapshot (path must be under the spawn-trees root). */
'spawn_tree.load': { params: SpawnTreeLoadParams; result: SpawnTreeLoadResult }
/** Persist a finished delegation tree snapshot under the session's spawn-trees dir. */
'spawn_tree.save': { params: SpawnTreeSaveParams; result: SpawnTreeSaveResult }
/** Hard-interrupt one owned child; ``found`` is false when it already finished. */
'subagent.interrupt': { params: SubagentIdParams; result: SubagentInterruptResult }
/** Live children owned by this session (other sessions' children never leak). */
'subagent.list': { params: SessionParams; result: SubagentListResult }
/** Per-conversation counts of live delegated children and running background processes, limited to conversations stored in the named profile (launch profile when omitted). Needs no attached session. */
'subagent.roster': { params: ProfileParams; result: SubagentRosterResult }
/** Queue steering text into a live delegated child owned by this session. */
'subagent.steer': { params: SubagentSteerParams; result: SubagentSteerResult }
/** Last 16KB of an owned child's live transcript. */
'subagent.tail': { params: SubagentIdParams; result: SubagentTailResult }
/** Schedule a downgrade / same-price change or a period-end cancellation. */
'subscription.change': { params: SubscriptionChangeParams; result: BillingPendingChangeResult }
/** Chargeless quote of what a plan change would do (billing:manage). */
'subscription.preview': { params: SubscriptionPreviewParams; result: SubscriptionPreviewResult }
/** Clear a scheduled downgrade / cancellation (re-enables recurring spend). */
'subscription.resume': { params: ProfileParams; result: BillingPendingChangeResult }
/** Current plan, tier catalog and usage for the picker; fail-open when logged out. */
'subscription.state': { params: ProfileParams; result: SubscriptionStateResult }
/** Prorate, charge and flip the plan (billing:manage, idempotent). */
'subscription.upgrade': { params: SubscriptionUpgradeParams; result: SubscriptionUpgradeResult }
/** Host battery for the status bar; always resolves, ``available: false`` when unreadable. */
'system.battery': { params: SystemBatteryParams; result: SystemBatteryResult }
/** Record the client's column width for server-side rendering. */
'terminal.resize': { params: TerminalResizeParams; result: TerminalResizeResult }
/** Persist a toolset / MCP enable-disable change and rebuild the session agent so it takes effect now. */
'tools.configure': { params: ToolsConfigureParams; result: ToolsConfigureResult }
/** Every toolset with its resolved tool names, flagged against the session's (or config's) enabled set. */
'tools.list': { params: _SessionScoped; result: ToolsetsListResult }
/** The /tools listing grouped by toolset, including tools deferred behind the tool_search bridge. */
'tools.show': { params: _SessionScoped; result: ToolsShowResult }
/** Toolset summaries (no tool names) for the desktop Toolsets tab. */
'toolsets.list': { params: _SessionScoped; result: ToolsetsListResult }
/** Two-bar dollar usage view shared by /usage, /topup and /subscription; fail-open to unavailable. */
'usage.bars': { params: ProfileParams; result: UsageModel }
/** Add a login / payment / address item to the local vault. */
'vault.add': { params: VaultAddParams; result: VaultAddResult }
/** Metadata-only listing across the local vault and every unlocked password manager. */
'vault.list': { params: ProfileParams; result: VaultListResult }
/** Forget a manager's session token (every manager when no name is given). */
'vault.lock': { params: VaultLockParams; result: VaultLockResult }
/** Remove a local vault item by id. */
'vault.remove': { params: VaultRemoveParams; result: VaultRemoveResult }
/** Enable or disable an external password manager (disabling also locks it). */
'vault.source.set': { params: VaultSourceSetParams; result: VaultSourceSetResult }
/** Status of every login source (local vault + detected password managers). */
'vault.sources': { params: ProfileParams; result: VaultSourcesResult }
/** Unlock a password manager for this session with its master password. */
'vault.unlock': { params: VaultUnlockParams; result: VaultUnlockResult }
/** Best known verification evidence for a cwd/session; read-only, never runs checks. */
'verification.status': { params: VerificationStatusParams; result: VerificationStatusResult }
/** VAD-bounded push-to-talk; the transcript arrives as a voice.transcript event. */
'voice.record': { params: VoiceRecordParams; result: VoiceRecordResult }
/** /voice parity: report, flip voice mode on/off, or toggle speech output. */
'voice.toggle': { params: VoiceToggleParams; result: VoiceToggleResult }
/** Speak text through the backend TTS engine (barge-in aware). */
'voice.tts': { params: VoiceTtsParams; result: VoiceTtsResult }
/** Push client-captured PCM into the armed detector (mic-less remote backends). */
'wake.feed': { params: WakeFeedParams; result: WakeFeedResult }
/** Release the mic (e.g. while the desktop's browser captures audio). */
'wake.pause': { params: WakeControlParams; result: WakePauseResult }
/** Reclaim the mic after a pause; no-op if the listener isn't armed. */
'wake.resume': { params: WakeControlParams; result: WakeResumeResult }
/** Arm the wake-word listener for the calling surface; refusals explain why. */
'wake.start': { params: WakeStartParams; result: WakeStartResult }
/** Everything a client needs to draw the wake-word state and decide whether to (re)arm. */
'wake.status': { params: WakeStatusParams; result: WakeStatusResult }
/** Stop this surface's listener; persist also writes wake_word.enabled: false. */
'wake.stop': { params: WakeStopParams; result: WakeStopResult }
}
export type RpcMethod = keyof RpcMethods
export const RPC_METHODS = [
'agents.list',
'approval.pending',
'approval.received',
'approval.respond',
'billing.auto_reload',
'billing.charge',
'billing.charge_status',
'billing.keep_going_on_credits',
'billing.state',
'billing.step_up',
'bot_relay.deliver',
'bot_relay.outbox.drain',
'bot_relay.reply',
'bot_relay.roster.sync',
'browser.manage',
'clarify.lock',
'cli.exec',
'client.capabilities',
'clipboard.paste',
'command.dispatch',
'command.resolve',
'commands.catalog',
'complete.path',
'complete.slash',
'config.get',
'config.set',
'config.show',
'connection.respond',
'connectors.accounts',
'connectors.accounts.remove',
'connectors.accounts.rename',
'connectors.catalog',
'connectors.connect',
'connectors.list',
'connectors.operation.status',
'connectors.operation.wake',
'connectors.policy.get',
'connectors.policy.set',
'connectors.tools',
'cron.manage',
'delegation.pause',
'delegation.status',
'diagnostics.share_nous',
'display.install',
'display.lease.acquire',
'display.lease.release',
'display.observe',
'display.start',
'display.status',
'display.stop',
'display.switchSandboxImage',
'display.thumbnail',
'file.attach',
'free_tier.ack_notice',
'free_tier.challenge_result',
'free_tier.claim_nudge',
'free_tier.provision',
'free_tier.status',
'gateway.capabilities',
'groups.approve',
'groups.attachment.download',
'groups.attachment.upload',
'groups.capabilities',
'groups.create',
'groups.demote',
'groups.disband',
'groups.discard',
'groups.list',
'groups.log',
'groups.peer.invite',
'groups.peer.register',
'groups.peer.revoke',
'groups.promote',
'groups.rename',
'groups.replica_state',
'groups.replicate',
'groups.retry',
'groups.send',
'groups.state',
'groups.stop',
'handoff.fail',
'handoff.request',
'handoff.state',
'i18n.catalog',
'i18n.languages',
'image.attach',
'image.attach_bytes',
'image.detach',
'image.generate',
'input.detect_drop',
'insights.get',
'learning.delete',
'learning.detail',
'learning.edit',
'learning.frames',
'llm.oneshot',
'machine.facts',
'mcp.catalog',
'mcp.servers.add',
'mcp.servers.list',
'mcp.servers.oauth.callback',
'mcp.servers.oauth.cancel',
'mcp.servers.oauth.poll',
'mcp.servers.oauth.start',
'mcp.servers.remove',
'mcp.servers.set_api_key',
'mcp.servers.status',
'mcp.servers.test',
'message.react',
'model.disconnect',
'model.options',
'model.save_key',
'onboarding.set_run',
'onboarding.skip',
'onboarding.start',
'onboarding.state',
'paste.collapse',
'pdf.attach',
'pet.cancel',
'pet.cells',
'pet.disable',
'pet.export',
'pet.gallery',
'pet.generate',
'pet.generate.status',
'pet.hatch',
'pet.info',
'pet.info.meta',
'pet.remove',
'pet.rename',
'pet.scale',
'pet.select',
'pet.thumb',
'ping',
'plugins.catalog.lookup',
'plugins.list',
'plugins.manage',
'preview.restart',
'process.kill',
'process.list',
'process.stop',
'profiles.configure',
'profiles.create',
'profiles.describe',
'profiles.get_asset',
'profiles.list',
'profiles.set_asset',
'project.facts',
'projects.add_folder',
'projects.archive',
'projects.create',
'projects.delete',
'projects.discover_repos',
'projects.for_cwd',
'projects.get',
'projects.list',
'projects.project_sessions',
'projects.record_repos',
'projects.remove_folder',
'projects.set_active',
'projects.set_primary',
'projects.tree',
'projects.update',
'prompt.background',
'prompt.btw',
'prompt.submit',
'reload.env',
'reload.mcp',
'request.answer',
'rollback.diff',
'rollback.list',
'rollback.restore',
'session.activate',
'session.active_list',
'session.archive',
'session.branch',
'session.branch_stored',
'session.branch_whole',
'session.close',
'session.compress',
'session.context_breakdown',
'session.control',
'session.control.read',
'session.create',
'session.cwd.set',
'session.delete',
'session.events.since',
'session.events.stats',
'session.foreign.import',
'session.foreign.list',
'session.foreign.preview',
'session.history',
'session.interrupt',
'session.list',
'session.most_recent',
'session.redirect',
'session.resume',
'session.save',
'session.set_hidden',
'session.status',
'session.steer',
'session.title',
'session.undo',
'session.usage',
'session.workspace.move',
'setup.runtime_check',
'setup.status',
'shared_metrics.desktop_daily',
'shared_metrics.desktop_dislike',
'shared_metrics.desktop_feature_use',
'shared_metrics.desktop_friction',
'shared_metrics.desktop_onboarding',
'shared_metrics.set',
'shared_metrics.slash_command',
'shared_metrics.startup_latency',
'shared_metrics.status',
'shared_metrics.update_run',
'shell.exec',
'skills.manage',
'skills.reload',
'slash.exec',
'spawn_tree.list',
'spawn_tree.load',
'spawn_tree.save',
'subagent.interrupt',
'subagent.list',
'subagent.roster',
'subagent.steer',
'subagent.tail',
'subscription.change',
'subscription.preview',
'subscription.resume',
'subscription.state',
'subscription.upgrade',
'system.battery',
'terminal.resize',
'tools.configure',
'tools.list',
'tools.show',
'toolsets.list',
'usage.bars',
'vault.add',
'vault.list',
'vault.lock',
'vault.remove',
'vault.source.set',
'vault.sources',
'vault.unlock',
'verification.status',
'voice.record',
'voice.toggle',
'voice.tts',
'wake.feed',
'wake.pause',
'wake.resume',
'wake.start',
'wake.status',
'wake.stop'
] as const satisfies readonly RpcMethod[]
// ── Canonical (hermes-gateway-v1) methods only the session authority serves ──
export interface CanonicalRpcMethods {
/** Forward one A2A input into the conversation its identity tuple names. */
'a2a.forward': { params: A2aForwardParams; result: A2aForwardResult }
'approval.respond': { params: CanonicalApprovalParams; result: PromptResponseResult }
'bot_relay.deliver': { params: CanonicalBotDeliverParams; result: CanonicalBotDeliverResult }
'bot_relay.settle': { params: CanonicalBotDeliverParams; result: CanonicalBotDeliverResult }
/** Lock one answer of the owner's batch clarify request (editable until every question is locked); only a viewer attached to that session with session:respond may lock. */
'clarify.lock': { params: ClarifyLockParams; result: ClarifyLockResult }
/** Generation-fenced answer to a pending clarify prompt (empty answer = skipped). */
'clarify.respond': { params: ClarifyRespondParams; result: PromptResponseResult }
/** Fire-only: a recognized command the classic CLI or the TUI runs itself; the gateway fires `pre_command` for it in the session's profile after replying (`queued` false: not fired). */
'command.observe': { params: CommandObserveParams; result: CommandObserveResult }
'config.get': { params: ConfigGetParams; result: CanonicalConfigGetResult }
'config.set': { params: CanonicalConfigSetParams; result: ConfigSetResult }
/** Cancel a queued cron admission or latch cancellation on a started one. */
'cron.cancel': { params: CronAdmissionParams; result: CronCancelResult }
/** Re-observe a firing after a scheduler restart (same request identity). */
'cron.recover': { params: CronRunParams; result: CronStatusResult }
/** Status and, once terminal, the result of one cron admission. */
'cron.status': { params: CronAdmissionParams; result: CronStatusResult }
/** Admit one cron firing into the owning profile's durable FIFO. */
'cron.submit': { params: CronRunParams; result: CronSubmitResult }
'groups.approve': { params: CanonicalRoomApproveParams; result: GroupsApproveResult }
/** Read one committed attachment for a live room viewer. */
'groups.attachment.download': { params: GroupsAttachmentDownloadParams; result: RoomAttachmentBytes }
/** Store one attachment for a later groups.send manifest (idempotent per upload_id). */
'groups.attachment.upload': { params: GroupsAttachmentUploadParams; result: RoomAttachment }
'groups.create': { params: CanonicalRoomCreateParams; result: GroupsCreateResult }
/** Discard one indeterminate room task after explicit user confirmation. */
'groups.discard': { params: GroupsDiscardParams; result: GroupsDiscardResult }
'groups.retry': { params: CanonicalRoomAttemptParams; result: GroupsRetryResult }
'image.attach_bytes': { params: ImageAttachBytesParams; result: CanonicalAttachedImageResult }
/** Native-owner only: admit the dispatcher's current claim on a kanban task. */
'kanban.run': { params: KanbanRunParams; result: KanbanRunResult }
'profiles.list': { params: CanonicalProfilesParams; result: CanonicalProfilesResult }
/** Retire a queued admission; a started one is interrupted in the same call. */
'prompt.cancel': { params: PromptCancelParams; result: AdmissionStatus }
/** Current receipt of one admission the caller submitted (or controls). */
'prompt.receipt': { params: PromptReceiptParams; result: PromptReceiptResult }
/** Cancel a still-queued admission and admit the edited prompt as a new admission at the back of the FIFO, in one write bound to the replaced admission. Refusals: admission_started, admission_conflict (the submission_id replaced another admission), queue_full, unsupported_control, not_found. */
'prompt.replace_queued': { params: CanonicalReplaceQueuedParams; result: AdmissionStatus }
/** Acknowledge a turn lost across an owner restart; the FIFO behind it resumes. Never requeues the lost input. */
'prompt.resolve_unknown': { params: PromptResolveUnknownParams; result: AdmissionStatus }
/** Hand a still-queued admission's text to the running turn's agent as a steer. The admission reads 'started' with that turn (pending snapshots mark it 'steering') and never runs on its own; it settles terminal 'steered' when the turn completes with its text, else 'interrupted' (its completion frame says 'cancelled', as an interrupted turn's does); a text the turn never consumed goes back to its queue place. Refusals: admission_started, session_idle, steer_unavailable (no agent to take it: the admission stays queued), unsupported_control, not_found. */
'prompt.steer_queued': { params: CanonicalSteerQueuedParams; result: AdmissionStatus }
'prompt.submit': { params: CanonicalSubmitParams; result: CanonicalSubmitResult }
/** The classic CLI's /diff session: everything changed since the session's earliest retained checkpoint, as data for its terminal renderer. */
'rollback.session_diff': { params: RollbackSessionDiffParams; result: RollbackSessionDiffResult }
/** Owner identity and the canonical capabilities a client may rely on. */
'runtime.describe': { params: RuntimeDescribeParams; result: RuntimeDescribeResult }
/** The classic CLI's /goal, /subgoal, /loop, /heartbeat manager calls (state writes, the goal judge, quality gates), run by the owner on the session's row. */
'session.automation': { params: SessionAutomationParams; result: SessionAutomationResult }
'session.create': { params: CanonicalCreateParams; result: CanonicalSnapshot }
/** Drop this connection's subscription; a stale subscription id answers detached=false. end_reason (snake_case): the viewer is closing the conversation; the last viewer leaving an idle local session ends its row with that reason. */
'session.detach': { params: SessionDetachParams; result: SessionDetachResult }
'session.events.since': { params: CanonicalEventsParams; result: CanonicalEventsResult }
/** The /save transcript rendered for the client to write (the gateway writes nothing). */
'session.export': { params: SessionExportParams; result: SessionExportResult }
/** Frozen launch policy projection of one local session. */
'session.info': { params: CanonicalSessionInfoParams; result: CanonicalSessionInfo }
'session.interrupt': { params: CanonicalControlParams; result: CanonicalSessionHandle }
'session.list': { params: CanonicalListParams; result: CanonicalListResult }
/** Revision-fenced, retry-idempotent session edit (rename, archive, sidebar, branch, delete, rewind, reset, model, reasoning, workspace, edit_policy, compress, import). */
'session.mutate': { params: SessionMutateParams; result: SessionMutateResult }
/** Local operator only: the owner deletes the ended sessions `hermes sessions prune` selected, skipping busy sessions and retained reset owners. */
'session.prune': { params: SessionPruneParams; result: SessionPruneResult }
'session.redirect': { params: CanonicalCorrectionParams; result: CanonicalCorrectionResult }
'session.resume': { params: CanonicalResumeParams; result: CanonicalSnapshot }
/** The session.usage dict on demand: what main's classic CLI read off its agent. */
'session.stats': { params: SessionStatsParams; result: SessionStats }
'session.steer': { params: CanonicalCorrectionParams; result: CanonicalCorrectionResult }
/** Ink ``!cmd`` / ``{!cmd}`` on the shared owner: one safe command for a local session, in its frozen launch cwd (``gateway/session_shell.py``). */
'shell.exec': { params: CanonicalShellExecParams; result: ShellExecResult }
/** Adopt a registered execution after verifying the live producer claim. */
'worker.adopt': { params: WorkerScopeParams; result: WorkerExecution }
/** Sequence-fenced typed persistence write from an adopted worker. */
'worker.persist': { params: WorkerPersistParams; result: WorkerPersistResult }
/** Register a compute worker execution on an idle session. */
'worker.register': { params: WorkerRegisterParams; result: WorkerExecution }
}
export type CanonicalRpcMethod = keyof CanonicalRpcMethods
export const CANONICAL_RPC_METHODS = [
'a2a.forward',
'approval.respond',
'bot_relay.deliver',
'bot_relay.settle',
'clarify.lock',
'clarify.respond',
'command.observe',
'config.get',
'config.set',
'cron.cancel',
'cron.recover',
'cron.status',
'cron.submit',
'groups.approve',
'groups.attachment.download',
'groups.attachment.upload',
'groups.create',
'groups.discard',
'groups.retry',
'image.attach_bytes',
'kanban.run',
'profiles.list',
'prompt.cancel',
'prompt.receipt',
'prompt.replace_queued',
'prompt.resolve_unknown',
'prompt.steer_queued',
'prompt.submit',
'rollback.session_diff',
'runtime.describe',
'session.automation',
'session.create',
'session.detach',
'session.events.since',
'session.export',
'session.info',
'session.interrupt',
'session.list',
'session.mutate',
'session.prune',
'session.redirect',
'session.resume',
'session.stats',
'session.steer',
'shell.exec',
'worker.adopt',
'worker.persist',
'worker.register'
] as const satisfies readonly CanonicalRpcMethod[]
// ── Server→client requests ──
export interface ServerRequestMap {
/** A dangerous command awaits the user's decision. */
approval: { params: ApprovalRequestParams; result: ApprovalResult }
/** The clarify tool: ask the user 1-5 questions. */
clarify: { params: ClarifyRequestParams; result: ClarifyResult }
/** Masked sudo password for the Bot Screen package install; app-level (empty session). */
'display.install.sudo': { params: DisplayInstallSudoParams; result: ValueResult }
/** Click / type / scroll / annotate inside the in-app browser preview. */
'preview.act': { params: PreviewActRequestParams; result: ValueResult }
/** Read the in-app browser preview's text (JSON text answer). */
'preview.read': { params: ReadRangeRequestParams; result: ValueResult }
/** Masked value for a named env var (skills / setup flows). */
secret: { params: SecretRequestParams; result: ValueResult }
/** The onboarding chat's card for one beat; blocks setup_beat until answered (300 s). */
setup_beat: { params: SetupBeatRequestParams; result: SetupBeatResult }
/** Masked sudo password for the terminal tool. */
sudo: { params: SudoRequestParams; result: ValueResult }
/** Read the visible in-app terminal buffer (JSON text answer). */
'terminal.read': { params: ReadRangeRequestParams; result: ValueResult }
/** Apply set_theme values in the window showing the session (JSON text answer). */
'theme.apply': { params: ThemeApplyRequestParams; result: ValueResult }
/** Show an accent or layout picker card in the chat and wait for the pick. */
'theme.pick': { params: ThemePickRequestParams; result: ThemePickResult }
/** Drive a guided tour highlight in the desktop renderer. */
tour: { params: TourRequestParams; result: ValueResult }
/** A one-time / 2FA code the user reads from their device. */
'vault.code': { params: VaultCodeRequestParams; result: ValueResult }
/** Save a login for a site the agent is about to fill; the answer is JSON {identifier, password}. */
'vault.save_login': { params: VaultSaveLoginRequestParams; result: ValueResult }
/** Master password to unlock an external password manager for this session. */
'vault.unlock_prompt': { params: VaultUnlockRequestParams; result: ValueResult }
/** Enumerate the native window below the app (JSON text answer). */
'window.read': { params: EmptyRequestParams; result: ValueResult }
}
export type ServerRequestMethod = keyof ServerRequestMap
export const SERVER_REQUEST_METHODS = [
'approval',
'clarify',
'display.install.sudo',
'preview.act',
'preview.read',
'secret',
'setup_beat',
'sudo',
'terminal.read',
'theme.apply',
'theme.pick',
'tour',
'vault.code',
'vault.save_login',
'vault.unlock_prompt',
'window.read'
] as const satisfies readonly ServerRequestMethod[]
// ── Notifications (`event` frames) ──
export interface BackendGatewayEventMap {
/** A status line the agent printed during a local viewer's turn. */
'agent.print': AgentPrintPayload
/** Output chunk from an agent-owned background process. */
'agent.terminal.output': TerminalOutputPayload
/** Pending gateway approvals were dropped by interrupt/reap/teardown; the wait resolved as deny (not a user refusal). */
'approval.cancelled': ApprovalCancelledPayload
/** A /background side agent finished. */
'background.complete': SideAgentCompletePayload
/** Device-flow URL + code for the billing scope step-up; the client opens the browser. */
'billing.step_up.verification': BillingStepUpVerificationPayload
/** A bot-relay outbox envelope is queued; drain it. */
'bot_relay.outbox.pending': ChangeSignalPayload
/** Browser (CDP) connect / install progress line. */
'browser.progress': BrowserProgressPayload
/** A /btw side question was answered. */
'btw.complete': SideAgentCompletePayload
/** A connection operation opened on this session; the desktop renders its card. */
'connection.request': ConnectionRequestPayload
/** One transition or the settlement of an open connection operation. */
'connection.update': ConnectionUpdatePayload
/** cron/jobs.json moved; refetch the cron list. */
'cron.changed': ChangeSignalPayload
/** The install ended (0 ok, -1 cancelled, -2 no sudo: the command to run by hand was streamed). */
'display.install.done': DisplayInstallDonePayload
/** One line of package-manager output. */
'display.install.log': DisplayInstallLogPayload
/** The takeover lease changed hands; every client repaints. */
'display.lease': DisplayLeasePayload
/** This profile's screen started or stopped (also for transitions made outside hermes serve). */
'display.status': DisplayStatusPayload
/** A session-level failure outside a turn (agent init, model switch, compression, resume). */
error: ErrorPayload
/** The account service wants a browser challenge cleared before the free-tier token exchange (broadcast); the desktop loads ``url`` in a hidden window. */
'free_tier.challenge': FreeTierChallengePayload
/** First frame of a connection: the resolved skin, the change-event capability and the replay epoch. */
'gateway.ready': GatewayReadyPayload
/** The turn ended: final text, usage and outcome. */
'message.complete': MessageCompletePayload
/** One streamed chunk of the assistant reply (null text: segment boundary). */
'message.delta': MessageDeltaPayload
/** Interim assistant commentary (text beside tool calls) sealed as its own segment. */
'message.interim': MessageInterimPayload
/** The agent reacted to a message; paint it live. */
'message.reaction': MessageReactionPayload
/** A turn began streaming; an automation turn carries its async-result card. */
'message.start': MessageStartPayload
/** The MoA aggregator started. */
'moa.aggregating': MoaAggregatingPayload
/** MoA phase transition (currently only ``aggregator``). */
'moa.phase': MoaPhasePayload
/** MoA reference fan-out progress (n/total). */
'moa.progress': MoaProgressPayload
/** One MoA reference model's output. */
'moa.reference': MoaReferencePayload
/** Informational one-liner for the session (capabilities refreshed). */
notice: NoticePayload
/** Withdraw the notice with this key. */
'notification.clear': NotificationClearPayload
/** Show / replace a keyed out-of-band notice (toast or status bar). */
'notification.show': NotificationShowPayload
/** A first-run onboarding run ended; sent to every connected window. */
'onboarding.ended': OnboardingEndedPayload
/** Pairing state moved; refetch pairing. */
'pairing.changed': ChangeSignalPayload
/** Focus / reveal a named desktop pane. */
'pane.reveal': PaneRevealPayload
/** The active pet / its spritesheet changed (watcher). */
'pet.changed': PetChangedPayload
/** Pet base-draft generation progress. */
'pet.generate.progress': PetGenerateProgressPayload
/** Pet hatch (row drawing) progress. */
'pet.hatch.progress': PetHatchProgressPayload
/** gateway_state.json moved; refetch platform status. */
'platforms.changed': ChangeSignalPayload
/** Close the preview pane or one tab. */
'preview.close': PreviewClosePayload
/** Open a URL / file in the desktop preview pane. */
'preview.open': PreviewOpenPayload
/** The hidden preview-restart agent finished. */
'preview.restart.complete': SideAgentCompletePayload
/** Progress line from the preview-restart agent. */
'preview.restart.progress': PreviewRestartProgressPayload
/** projects.db moved; refetch the project list + tree. */
'projects.changed': ChangeSignalPayload
/** Affection reaction detected in the user's message (hearts etc.). */
reaction: ReactionPayload
/** A completed reasoning block (non-streaming providers). */
'reasoning.available': StreamDeltaPayload
/** One streamed chunk of the model's reasoning. */
'reasoning.delta': StreamDeltaPayload
/** The backend withdrew an open server→client request; clear the matching card only. */
'request.cancel': RequestCancelPayload
/** Background review of the last turn finished. */
'review.summary': ReviewSummaryPayload
/** Persisted goal / loop / heartbeat state changed. */
'session.control.update': SessionControlUpdatePayload
/** Live session settings snapshot (``server._session_info``); also the ``info`` of create/resume/activate. */
'session.info': SessionLiveInfo
/** The backend reclaimed a live session out from under its clients. */
'session.reclaimed': SessionReclaimedPayload
/** Deferred resume hydration progress. */
'session.resume_progress': SessionResumeProgressPayload
/** Auto-titling renamed the session (``session_id`` is the stored key). */
'session.title': SessionTitlePayload
/** Mid-turn usage tick; message.complete carries the authoritative final usage. */
'session.usage': SessionUsagePayload
/** state.db moved; refetch the session list. */
'sessions.changed': ChangeSignalPayload
/** The free-tier bootstrap finished (broadcast); the desktop's setup gate reads the record. */
'setup.ready': SetupReadyPayload
/** A skill root moved (installed/removed elsewhere); refetch commands.catalog from the gateway. */
'skills.changed': ChangeSignalPayload
/** The active skin moved (name switch or live colour edit); repaint from this palette. */
'skin.changed': SkinPayload
/** Transient status line (kind: status, lifecycle, compacting, goal, loop, heartbeat, process, …). */
'status.update': StatusUpdatePayload
/** A child finished (status + observability rollup). */
'subagent.complete': SubagentEventPayload
/** Batched tool-name progress from a child. */
'subagent.progress': SubagentEventPayload
/** delegate_task accepted a child goal (before the child starts). */
'subagent.spawn_requested': SubagentEventPayload
/** A delegated child started running. */
'subagent.start': SubagentEventPayload
/** A child's reasoning chunk. */
'subagent.thinking': SubagentEventPayload
/** A child called a tool. */
'subagent.tool': SubagentEventPayload
/** An agent-owned background process closed. */
'terminal.close': TerminalClosePayload
/** Legacy thinking-text chunk (thinking_callback). */
'thinking.delta': StreamDeltaPayload
/** Point at a desktop element with a one-line tip bubble. */
'tip.show': TipShowPayload
/** Full todo snapshot after a todo tool ran. */
'todo.updated': TodoUpdatedPayload
/** A tool call finished: parsed result, summary, optional diff / todo snapshot. */
'tool.complete': ToolCompletePayload
/** The model is emitting a tool call's arguments. */
'tool.generating': ToolGeneratingPayload
/** Tool output was classified as risky (prompt-injection / secret findings). */
'tool.output_risk': ToolOutputRiskPayload
/** Live progress of a running tool call (MCP notifications/progress). */
'tool.progress': ToolProgressPayload
/** A tool call began (stable id + full args). */
'tool.start': ToolStartPayload
/** Barge-in: the spoken interjection interrupted the turn; no payload. */
'voice.interrupted': Record<string, never>
/** Live STT text so far while the user is still speaking. */
'voice.partial': VoicePartialPayload
/** Voice recorder state changed. */
'voice.status': VoiceStatusPayload
/** A voice capture produced text (or a stop phrase / silence limit). */
'voice.transcript': VoiceTranscriptPayload
/** A wake phrase fired. */
'wake.detected': WakeDetectedPayload
}
export type BackendGatewayEventName = keyof BackendGatewayEventMap
export const GATEWAY_EVENT_TYPES = [
'agent.print',
'agent.terminal.output',
'approval.cancelled',
'background.complete',
'billing.step_up.verification',
'bot_relay.outbox.pending',
'browser.progress',
'btw.complete',
'connection.request',
'connection.update',
'cron.changed',
'display.install.done',
'display.install.log',
'display.lease',
'display.status',
'error',
'free_tier.challenge',
'gateway.ready',
'message.complete',
'message.delta',
'message.interim',
'message.reaction',
'message.start',
'moa.aggregating',
'moa.phase',
'moa.progress',
'moa.reference',
'notice',
'notification.clear',
'notification.show',
'onboarding.ended',
'pairing.changed',
'pane.reveal',
'pet.changed',
'pet.generate.progress',
'pet.hatch.progress',
'platforms.changed',
'preview.close',
'preview.open',
'preview.restart.complete',
'preview.restart.progress',
'projects.changed',
'reaction',
'reasoning.available',
'reasoning.delta',
'request.cancel',
'review.summary',
'session.control.update',
'session.info',
'session.reclaimed',
'session.resume_progress',
'session.title',
'session.usage',
'sessions.changed',
'setup.ready',
'skills.changed',
'skin.changed',
'status.update',
'subagent.complete',
'subagent.progress',
'subagent.spawn_requested',
'subagent.start',
'subagent.thinking',
'subagent.tool',
'terminal.close',
'thinking.delta',
'tip.show',
'todo.updated',
'tool.complete',
'tool.generating',
'tool.output_risk',
'tool.progress',
'tool.start',
'voice.interrupted',
'voice.partial',
'voice.status',
'voice.transcript',
'wake.detected'
] as const satisfies readonly BackendGatewayEventName[]