hermes-agent/tui_gateway/contracts/connectors_operation.py
Siddharth Balyan 8365cae594
Catalog install card: plugin and skill rows with an Advanced install modal (#119633)
* feat(desktop): catalog install card rows for plugin and skill targets

manage_catalog opens the same connection operation manage_connections does,
with rows of kind plugin/skill. The renderer collapsed every non-connector
kind to 'mcp', so those rows would have drawn as MCP servers with no name,
purpose or provenance.

- Contract: ConnectionTargetKind gains plugin/skill; ConnectionOperationTarget
  types the catalog fields agreed in CATALOG-ROW-CONTRACT.md (display,
  description, tier, platforms, repo, sha, subdir, scan, requirements,
  has_desktop_half, target_profile, app_state, skill).
- Store: kinds map through a lookup; catalog rows carry a typed CatalogEntry.
- CatalogRow: kind glyph, name, kind/tier/platform pills, one-line purpose,
  then Install / Advanced / Skip. Installing shows the backend's per-row
  detail; installed shows "N tools · show names"; failed shows the reason
  and Try again (approved again for that row only); skipped stays quiet.
- Advanced: a centred dialog with the Plugins-tab controls (halves, target
  profile, enable, force, pin) plus read-only source and scan. Its Install
  sends the values in the answer env; the row's Install sends env null.
- A missed tool.start restores the card on a manage_catalog row.

* fix(desktop): catalog row uses the app's sliding progress and one pill style

The installing row drew a full-width pulsing line, which reads as a finished
rule, not work in progress; it now uses the Progress primitive's sliding
indeterminate block (reduced motion honoured there). The kind pill was
all-caps monospace next to two sentence-case pills; all three now share one
shape, matching the V1 offer artboard, and the platform pill stays the one
coloured note. The Advanced modal's Source and Security tables share a fixed
label column, and requirements render as prose, not code.

* fix(desktop): a skill's Advanced shows only the controls a skill has

A skill has no agent/desktop halves, no enable step and no commit pin, so
its Advanced dialog offered three controls that do nothing. It now shows the
target profile, force reinstall, source, security and credentials, and sends
only target_profile, force and the credential values. The preparing line
takes the card's width instead of the whole chat column.
2026-09-23 05:11:35 +05:30

238 lines
7.4 KiB
Python

"""The connection operation (``manage_connections`` card): the request event that opens a card,
the update frames that drive it, and the RPCs the card answers through.
Shapes are typed from ``tools/connectors/operation.py`` (``Target.snapshot``,
``ConnectionOperation.request_payload`` / ``_snapshot_locked``) and
``tui_gateway/methods_connectors.py`` (``_operation_view``, ``_connection_update``). The card is a
projection: every frame carries the full target snapshot, and the renderer never derives state.
"""
from __future__ import annotations
from typing import Literal
from pydantic import Field
from .base import Params, Payload, Result, WireEnum
from .common import ConnectorOwner, ProfileParams
from .registry import event, method
class ConnectionTargetKind(WireEnum):
connector = "connector"
mcp = "mcp"
# ``manage_catalog`` rows: a catalog plugin (may bring MCP tools and/or skills) or a skill.
plugin = "plugin"
skill = "skill"
class ConnectionTargetAction(WireEnum):
authorize = "authorize"
connect = "connect"
enable = "enable"
install = "install"
reconnect = "reconnect"
class ConnectionTargetState(WireEnum):
"""``tools/connectors/contract.py::TargetState``."""
pending = "pending"
initiated = "initiated"
connected = "connected"
skipped = "skipped"
failed = "failed"
expired = "expired"
not_connected = "not_connected"
class ConnectionActor(WireEnum):
"""``tools/connectors/contract.py::Actor``."""
user = "user"
backend_watcher = "backend_watcher"
clock = "clock"
class ConnectionSettleReason(WireEnum):
"""``tools/connectors/contract.py::SettleReason``."""
all_resolved = "all_resolved"
continue_ = "continue"
deadline = "deadline"
interrupt = "interrupt"
class ConnectionTargetEnvField(Payload):
"""One credential an MCP install still needs; the card renders a field per entry and sends the
values back with the approval."""
name: str
required: bool
secret: bool
default: str
prompt: str | None = None
class CatalogTier(WireEnum):
official = "official"
community = "community"
class CatalogAppState(WireEnum):
"""The desktop app a catalog plugin drives, from its ``hermes_platform`` declaration."""
present = "present"
missing_app = "missing_app"
app_not_running = "app_not_running"
unknown = "unknown"
class CatalogScanStatus(WireEnum):
passed = "passed"
warnings = "warnings"
failed = "failed"
class CatalogScan(Payload):
"""The catalog's security scan of the pinned commit; read-only on the card."""
status: CatalogScanStatus
summary: str
class ConnectionOperationTarget(Payload):
"""``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."""
name: str
kind: ConnectionTargetKind
action: ConnectionTargetAction
state: ConnectionTargetState
detail: str | None = None
instructions: str | None = None
discovery_error: str | None = None
connect_url: str | None = None
# The vendor account a managed mint created or observed; never the desktop transport's id.
connection_id: str | None = None
attempt: str | None = None
# Present only on an MCP install that is waiting for credentials.
required_env: list[ConnectionTargetEnvField] | None = None
tools: list[str] | None = None
hint: str | None = None
# Catalog rows (kind ``plugin`` / ``skill``) only; field set agreed in CATALOG-ROW-CONTRACT.md.
display: str | None = None
description: str | None = None
tier: CatalogTier | None = None
platforms: list[str] | None = None
repo: str | None = None
sha: str | None = None
subdir: str | None = None
scan: CatalogScan | None = None
requirements: list[str] | None = None
has_desktop_half: bool | None = None
target_profile: str | None = None
app_state: CatalogAppState | None = None
# On an installed skill row: the qualified skill name the model can now load.
skill: str | None = None
class ConnectionRequestPayload(Payload):
"""``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."""
op_id: str
# Monotonic write counter for the operation; a frame whose seq is not higher than the one the
# renderer holds is older and moves no row.
seq: int
deadline_at: float
timeout_seconds: float
targets: list[ConnectionOperationTarget]
# The model's id for the call that opened the operation; the card binds to that tool row only.
tool_call_id: str | None = None
event("connection.request", ConnectionRequestPayload,
doc="A connection operation opened on this session; the desktop renders its card.")
class ConnectionOperationStatus(Result):
"""``methods_connectors._operation_view``: the operation's full snapshot."""
op_id: str
seq: int
deadline_at: float
settled: bool
settled_at: float | None = None
settled_by: ConnectionSettleReason | None = None
targets: list[ConnectionOperationTarget]
class ConnectionUpdatePayload(ConnectionOperationStatus, Payload):
"""``methods_connectors._connection_update``: one target transition (``target``/``from``/``to``/
``actor``) or the settlement (none of those), with the full snapshot."""
owner: ConnectorOwner
target: str | None = None
from_: ConnectionTargetState | None = Field(default=None, alias="from") # ``from`` is a keyword
to: ConnectionTargetState | None = None
actor: ConnectionActor | None = None
detail: str | None = None
event("connection.update", ConnectionUpdatePayload,
doc="One transition or the settlement of an open connection operation.")
class ConnectionOperationParams(ProfileParams):
owner: ConnectorOwner
op_id: str
method("connectors.operation.status", params=ConnectionOperationParams, result=ConnectionOperationStatus,
doc="The current snapshot of one open session or account operation.")
class ConnectionWakeResult(Result):
status: Literal["ok"]
method("connectors.operation.wake", params=ConnectionOperationParams, result=ConnectionWakeResult,
doc="The browser leg came back (hermes://connections/done): read the accounts now, not at the next tick.")
class ConnectionAnswerStatus(WireEnum):
"""What the card says about one row: ``tools/connectors/mcp.py::apply_answer``."""
approved = "approved"
skipped = "skipped"
class ConnectionAnswerTarget(Params):
"""One row's answer from the card. ``env`` carries the credential values an install asked for
through ``required_env``."""
name: str
status: ConnectionAnswerStatus
detail: str | None = None
env: dict[str, str] | None = None
class ConnectionAnswer(Params):
"""The card's answer: per-target outcomes and an optional Continue
(``settled_by: "continue"``). Settlement is derived from target states afterwards."""
targets: list[ConnectionAnswerTarget] = Field(default_factory=list)
settled_by: ConnectionSettleReason | None = None
class ConnectionRespondParams(ConnectionOperationParams):
result: ConnectionAnswer
class ConnectionRespondResult(Result):
status: Literal["ok"]
settled: bool
method("connection.respond", params=ConnectionRespondParams, result=ConnectionRespondResult,
doc="Per-target outcomes from the card, and an optional Continue.")