Files
hermes-agent/ui-tui/src/types.ts
T
teknium1 36773e0d78 refactor(ts): one GatewayEventMap in apps/shared typed from tui_gateway emitters; drop never-emitted tool.progress
Three TypeScript clients each declared their own copy of the tui_gateway wire
types and had drifted apart: apps/shared had a partial GatewayEventName union
with a `(string & {})` escape hatch, ui-tui/gatewayTypes.ts a 150-line
discriminated union, and apps/desktop an `RpcEvent<T>` that was field-for-field
the shared GatewayEvent with `type: string`. None matched the emitter:
message.complete lacked warning/status/error/recoverable/error_surface,
tool.start/tool.complete lacked args/result, SessionResumeResponse lacked
session_key/messages_omitted/hydrating/auto_continue/todo_state, three
different ModelOptionProvider shapes disagreed on fields, and all three unions
handled a `tool.progress` event that no Python emitter has ever produced.

Now:

* `apps/shared/src/gateway-events.ts` is the single home: payload interfaces
  typed from the Python emitters (file::symbol cited per interface),
  `BackendGatewayEventMap` (89 backend names) + `ClientLocalGatewayEventMap`
  (5 TUI-synthetic transport events, clearly marked, excluded from the
  contract) merged into `GatewayEventMap`; `GatewayEvent<K>` is discriminated
  on `type` with `seq` typed. RPC shapes shared by 2+ surfaces live beside it
  (ModelOptionProvider = union of every field hermes_cli/inventory.py sets,
  incl. pricing_pending/free_tier_pending; SessionResumeResponse<Info>;
  SessionListItem with resolved_id; Usage).
* `JsonRpcGatewayClient.on<K>` is keyed by event name; the gateway.ready
  heartbeat/replay_epoch and per-frame `seq` reads are typed instead of cast.
* ui-tui and apps/desktop import the shared names; their local duplicates are
  deleted (no re-export shims — importers are repointed; the desktop plugin
  SDK barrel keeps its public `RpcEvent` name as an alias of GatewayEvent).
  web/src repoints ModelOptionProvider/ModelOptionsResponse.
* `tool.progress` handling is removed from the TUI handler/turnController,
  desktop event sets/tools handler, shared union, tests, and two docs
  (`grep '"tool.progress"' tui_gateway/` = 0 hits; the `display.tool_progress`
  config mode is unrelated and untouched).
* `message.complete.warning` (history-commit note from
  prompt_turn.py::_complete_turn_payload) is typed and surfaced on both
  surfaces through their existing notice paths (TUI pushActivity 'warn',
  desktop notify kind 'warning').

Contract: `apps/shared/src/gateway-events.json` is the sorted list of
backend-emitted names. `tests/tui_gateway/test_gateway_event_contract.py`
collects names from the Python emitter side (emit-helper literals, the
`.request → .expire` table, change-watcher table, child delta mirror,
subagent relay, desktop_ui tool emitters, gateway.ready/setup.ready/
browser-controller frames) and asserts emitted == JSON in both directions.
`apps/shared/src/gateway-events.test.ts` asserts BACKEND_EVENT_NAMES (which
the map type is `satisfies`-checked against) == JSON. Sabotage-verified: a
fake JSON name fails both tests; a fake TS name fails tsc + vitest; a fake
Python `_emit("...")` fails pytest.
2026-09-13 05:42:31 -07:00

253 lines
6.3 KiB
TypeScript

import type { SubagentStatus, Usage } from '@hermes/shared/gateway-events'
export interface ActiveTool {
context?: string
id: string
name: string
verboseArgs?: string
startedAt?: number
}
export interface TodoItem {
content: string
id: string
/** Optional id of another item — renders this as a nested subtask. */
parent?: string
status: 'cancelled' | 'completed' | 'in_progress' | 'pending'
}
export interface ActivityItem {
id: number
text: string
tone: 'error' | 'info' | 'warn'
}
export interface SubagentProgress {
apiCalls?: number
costUsd?: number
/** Batch (delegation) id — tags `[n/N]` rows so concurrent/nested fan-outs
* are distinguishable. Absent on older gateways. */
delegationId?: string
depth: number
durationSeconds?: number
filesRead?: string[]
filesWritten?: string[]
goal: string
id: string
index: number
inputTokens?: number
iteration?: number
model?: string
notes: string[]
outputTail?: SubagentOutputEntry[]
outputTokens?: number
parentId: null | string
reasoningTokens?: number
startedAt?: number
status: SubagentStatus
summary?: string
taskCount: number
thinking: string[]
toolCount: number
tools: string[]
toolsets?: string[]
}
export interface SubagentOutputEntry {
isError: boolean
preview: string
tool: string
}
export interface SubagentNode {
aggregate: SubagentAggregate
children: SubagentNode[]
item: SubagentProgress
}
export interface SubagentAggregate {
activeCount: number
costUsd: number
descendantCount: number
filesTouched: number
hotness: number
inputTokens: number
maxDepthFromHere: number
outputTokens: number
totalDuration: number
totalTools: number
}
export interface DelegationStatus {
active: {
depth?: number
goal?: string
model?: null | string
parent_id?: null | string
started_at?: number
status?: string
subagent_id?: string
tool_count?: number
}[]
max_concurrent_children?: number
max_spawn_depth?: number
paused: boolean
}
export interface ApprovalReq {
// false when the backend won't honor a permanent allow (tirith warning) → hide "Always allow".
allowPermanent?: boolean
choices?: string[]
command: string
description: string
smartDenied?: boolean
}
export interface ConfirmReq {
cancelLabel?: string
confirmLabel?: string
danger?: boolean
detail?: string
onConfirm: () => void
title: string
}
export interface ClarifyBatchQuestion {
choices: string[] | null
multiSelect?: boolean
qid: string
question: string
}
export interface ClarifyReq {
choices: string[] | null
question: string
requestId: string
/** Batch (multi-question) clarify: present instead of question/choices. */
questions?: ClarifyBatchQuestion[]
/** Answers already locked server-side (qid → answer): seeded from the
* reconnect replay, updated as the user locks each question. */
answers?: Record<string, string>
}
export interface Msg {
info?: SessionInfo
kind?: 'diff' | 'event' | 'intro' | 'panel' | 'slash' | 'trail'
panelData?: PanelData
role: Role
text: string
// Unix seconds the message was authored (persisted transcript timestamp on
// rehydrate, wall clock at append time for live rows). Rendered as a dim
// [HH:MM] label when `display.timestamps` is on (#41531).
createdAt?: number
thinking?: string
// MoA reference-model output stored in `thinking` (see turnController's
// recordMoaReference): unlike ordinary model reasoning, this is the
// user-facing mixture-of-agents process the user opted into, so it stays
// visible even when `display.sections.thinking` is hidden.
isMoaReference?: boolean
// True only while this trail segment's reasoning is being streamed live by
// the current turn (see turnController's syncReasoningSegment). Sealed
// reasoning segments from earlier in the turn carry no flag, so the TUI can
// tell "the reasoning happening right now" apart from finished blocks.
isLiveReasoning?: boolean
thinkingTokens?: number
toolTokens?: number
tools?: string[]
todos?: TodoItem[]
todoIncomplete?: boolean
todoCollapsedByDefault?: boolean
}
export type Role = 'assistant' | 'system' | 'tool' | 'user'
export type DetailsMode = 'hidden' | 'collapsed' | 'expanded'
export type ThinkingMode = 'collapsed' | 'truncated' | 'full'
// Per-section overrides for the agent details accordion. Resolution order
// at lookup time is: explicit `display.sections.<name>` → built-in
// SECTION_DEFAULTS → global `details_mode`. Today the built-in defaults
// expand `thinking`/`tools` and hide `activity`; `subagents` falls through
// to the global mode. Any explicit value still wins for that one section.
export type SectionName = 'thinking' | 'tools' | 'subagents' | 'activity'
export type SectionVisibility = Partial<Record<SectionName, DetailsMode>>
export interface McpServerStatus {
connected: boolean
disabled?: boolean
status?: 'configured' | 'connecting' | 'connected' | 'disabled' | 'failed'
name: string
tools: number
transport: string
}
export interface ProjectInfo {
id: string
name: string
primary_path?: null | string
slug: string
}
export interface SessionInfo {
cwd?: string
fast?: boolean
install_warning?: string
lazy?: boolean
mcp_servers?: McpServerStatus[]
model: string
profile_name?: string
project?: null | ProjectInfo
reasoning_effort?: string
running?: boolean
release_date?: string
service_tier?: string
skills: Record<string, string[]>
system_prompt?: string
tools: Record<string, string[]>
update_behind?: number | null
update_command?: string
usage?: Usage
version?: string
}
export interface SudoReq {
requestId: string
}
export interface SecretReq {
envVar: string
prompt: string
requestId: string
}
/** External password-manager unlock (1Password / Bitwarden) — masked master-password prompt. */
export interface VaultUnlockReq {
backend: string
displayName: string
requestId: string
}
export interface PanelData {
sections: PanelSection[]
title: string
}
export interface PanelSection {
items?: string[]
rows?: [string, string][]
text?: string
title?: string
}
export interface SlashCatalog {
canon: Record<string, string>
categories: SlashCategory[]
pairs: [string, string][]
skillCount: number
sub: Record<string, string[]>
}
export interface SlashCategory {
name: string
pairs: [string, string][]
}