mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-11-17 04:11:35 +00:00
696 lines
24 KiB
Python
696 lines
24 KiB
Python
"""Contracts: config, setup readiness, free tier, model inventory, connectors, diagnostics,
|
|
image generation and structured session control.
|
|
|
|
Handlers: ``tui_gateway/methods_config.py`` (``config.get``, ``setup.*``, ``diagnostics.share_nous``),
|
|
``methods_config_set.py`` (``config.set``), ``methods_free_tier.py``, ``methods_shared_metrics.py``,
|
|
``methods_complete.py``
|
|
(``model.options``), ``methods_connectors.py``, ``methods_images.py``, ``methods_session_control.py``
|
|
and ``methods_session.py`` (``verification.status``).
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
from typing import Literal
|
|
|
|
from pydantic import Field
|
|
|
|
from .base import JsonValue, Params, Result, WireEnum
|
|
from .common import OkResult, OpenModel, ProfileParams, SessionLiveInfo
|
|
from .registry import method
|
|
|
|
# ── config.get ────────────────────────────────────────────────────────────────────────────────
|
|
|
|
|
|
class ConfigGetParams(ProfileParams):
|
|
"""``key`` selects one getter from ``_CONFIG_GETTERS``; ``cwd`` feeds the ``project`` getter,
|
|
``session_id`` lets ``reasoning`` / ``fast`` answer with the session's live pin."""
|
|
|
|
key: str
|
|
cwd: str | None = None
|
|
session_id: str | None = None
|
|
|
|
|
|
class ConfigProviderRef(OpenModel):
|
|
"""``hermes_cli/models.py::list_available_providers`` row."""
|
|
|
|
id: str
|
|
label: str
|
|
aliases: list[str] = Field(default_factory=list)
|
|
authenticated: bool = False
|
|
|
|
|
|
class ConfigGetResult(Result):
|
|
"""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``."""
|
|
|
|
value: str | None = None
|
|
display: str | None = None
|
|
tool_progress: str | None = None
|
|
model: str | None = None
|
|
provider: str | None = None
|
|
providers: list[ConfigProviderRef] | None = None
|
|
home: str | None = None
|
|
cwd: str | None = None
|
|
branch: str | None = None
|
|
config: dict[str, JsonValue] | None = None
|
|
prompt: str | None = None
|
|
mtime: float | None = None
|
|
mcp_rev: str | None = None
|
|
|
|
|
|
method("config.get", params=ConfigGetParams, result=ConfigGetResult,
|
|
doc="Read one normalised config value (or the whole effective config) the way the UIs render it.")
|
|
|
|
|
|
# ── config.set ────────────────────────────────────────────────────────────────────────────────
|
|
|
|
|
|
class ConfigSetScope(WireEnum):
|
|
session = "session"
|
|
global_ = "global"
|
|
once = "once"
|
|
|
|
|
|
class ConfigSetParams(ProfileParams):
|
|
"""``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``."""
|
|
|
|
key: str
|
|
value: JsonValue = ""
|
|
session_id: str | None = None
|
|
scope: str | None = None
|
|
confirm_expensive_model: bool = False
|
|
|
|
|
|
class ConfigSetResult(Result):
|
|
"""``{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."""
|
|
|
|
key: str
|
|
value: str | bool | None = None
|
|
warning: str | None = None
|
|
confirm_required: bool | None = None
|
|
confirm_message: str | None = None
|
|
scope: str | None = None
|
|
deferred: bool | None = None
|
|
tool_progress: str | None = None
|
|
cwd: str | None = None
|
|
branch: str | None = None
|
|
history_reset: bool | None = None
|
|
info: SessionLiveInfo | None = None
|
|
|
|
|
|
method("config.set", params=ConfigSetParams, result=ConfigSetResult,
|
|
doc="Change one config key (persisted or session-scoped) and read back the normalised value.")
|
|
|
|
|
|
# ── setup readiness ───────────────────────────────────────────────────────────────────────────
|
|
|
|
|
|
class SetupStatusResult(Result):
|
|
"""``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``."""
|
|
|
|
provider_configured: bool | None = None
|
|
ready: bool | None = None
|
|
free_tier_account: bool | None = None
|
|
free_tier_route: bool | None = None
|
|
other_providers: bool | None = None
|
|
inference_provider: str | None = None
|
|
profile: str | None = None
|
|
ok: bool | None = None
|
|
error: str | None = None
|
|
error_code: str | None = None
|
|
retryable: bool | None = None
|
|
retry_after: int | None = None
|
|
|
|
|
|
method("setup.status", params=ProfileParams, result=SetupStatusResult,
|
|
doc="Loose provider check: is ANY provider auth state discoverable for the (launch or named) profile.")
|
|
|
|
|
|
class SetupRuntimeCheckParams(ProfileParams):
|
|
provider: str | None = None
|
|
|
|
|
|
class SetupRuntimeCheckResult(Result):
|
|
"""``ok=False`` + ``error`` when the resolved model can't be served; ``free_tier_route`` says the
|
|
selected route is the welcome host."""
|
|
|
|
ok: bool
|
|
provider: str | None = None
|
|
model: str | None = None
|
|
source: str | None = None
|
|
error: str | None = None
|
|
free_tier_route: bool | None = None
|
|
profile: str | None = None
|
|
|
|
|
|
method("setup.runtime_check", params=SetupRuntimeCheckParams, result=SetupRuntimeCheckResult,
|
|
doc="Strict provider check through the same runtime resolution the agent uses on session creation.")
|
|
|
|
|
|
# ── diagnostics.share_nous ────────────────────────────────────────────────────────────────────
|
|
|
|
|
|
class DiagnosticsShareNousParams(Params):
|
|
error_context: str | None = None
|
|
extra_files: dict[str, str] | None = None
|
|
log_lines: int | None = None
|
|
|
|
|
|
class DiagnosticsShareNousResult(Result):
|
|
"""Structured envelope: ``ok=False`` + ``error`` renders inline instead of failing the RPC."""
|
|
|
|
ok: bool
|
|
view_url: str | None = None
|
|
upload_id: str | None = None
|
|
expires_at: str | None = None
|
|
error: str | None = None
|
|
|
|
|
|
method("diagnostics.share_nous", params=DiagnosticsShareNousParams, result=DiagnosticsShareNousResult,
|
|
doc="Upload a force-redacted debug bundle to Nous-internal diagnostics storage.")
|
|
|
|
|
|
# ── free tier ─────────────────────────────────────────────────────────────────────────────────
|
|
|
|
|
|
class FreeTierStatusResult(Result):
|
|
"""``available`` = an identity exists AND the tier is on; whether inference runs on it is
|
|
``setup.runtime_check.free_tier_route``'s question."""
|
|
|
|
has_guest: bool
|
|
enabled: bool
|
|
available: bool
|
|
notice_pending: bool
|
|
model: str
|
|
label: str
|
|
error: str | None = None
|
|
error_code: str | None = None
|
|
retryable: bool | None = None
|
|
retry_after: int | None = None
|
|
|
|
|
|
method("free_tier.status", params=ProfileParams, result=FreeTierStatusResult,
|
|
doc="Pure read of the focused profile's free-tier identity state (no network, no side effects).")
|
|
|
|
|
|
class FreeTierProvisionResult(Result):
|
|
has_guest: bool
|
|
enabled: bool
|
|
error: str | None = None
|
|
error_code: str | None = None
|
|
retryable: bool | None = None
|
|
retry_after: int | None = None
|
|
|
|
|
|
method("free_tier.provision", params=ProfileParams, result=FreeTierProvisionResult,
|
|
doc="Explicit retry of the free-tier identity mint when the boot bootstrap could not create it.")
|
|
|
|
|
|
class FreeTierAckNoticeResult(Result):
|
|
acked: bool
|
|
|
|
|
|
method("free_tier.ack_notice", params=ProfileParams, result=FreeTierAckNoticeResult,
|
|
doc="Mark the one-time availability notice as shown on the free-tier identity.")
|
|
|
|
|
|
# ── shared metrics consent ────────────────────────────────────────────────────────────────────
|
|
|
|
|
|
class SharedMetricsConsentResult(Result):
|
|
"""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)."""
|
|
|
|
enabled: bool
|
|
send: bool
|
|
decided: bool
|
|
|
|
|
|
method("shared_metrics.status", params=ProfileParams, result=SharedMetricsConsentResult,
|
|
doc="Pure read of the focused profile's shared-metrics opt-ins (collection, upload, answered).")
|
|
|
|
|
|
class SharedMetricsSetParams(ProfileParams):
|
|
"""``send`` is ignored unless ``enabled``; ``first_run`` marks the Desktop first-run answer."""
|
|
|
|
enabled: bool
|
|
send: bool = False
|
|
first_run: bool = False
|
|
|
|
|
|
method("shared_metrics.set", params=SharedMetricsSetParams, result=SharedMetricsConsentResult,
|
|
doc="Write both shared-metrics opt-ins at once (send requires collection) and reconcile consent windows.")
|
|
|
|
|
|
class SharedMetricsSlashCommandParams(ProfileParams):
|
|
"""``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."""
|
|
|
|
command: str
|
|
session_id: str | None = None
|
|
|
|
|
|
class SharedMetricsSlashCommandResult(Result):
|
|
ok: bool
|
|
|
|
|
|
method("shared_metrics.slash_command", params=SharedMetricsSlashCommandParams,
|
|
result=SharedMetricsSlashCommandResult,
|
|
doc="Count one user-typed slash command (fire-and-forget; a no-op unless shared metrics are on).")
|
|
|
|
|
|
class SharedMetricsStartupLatencyParams(ProfileParams):
|
|
"""``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."""
|
|
|
|
elapsed_ms: float
|
|
surface: Literal["desktop_attach", "tui"] | None = None
|
|
launch_id: str | None = None
|
|
|
|
|
|
class SharedMetricsStartupLatencyResult(Result):
|
|
ok: bool
|
|
|
|
|
|
method("shared_metrics.startup_latency", params=SharedMetricsStartupLatencyParams,
|
|
result=SharedMetricsStartupLatencyResult,
|
|
doc="Record one client launch-to-ready latency (fire-and-forget; a no-op unless shared metrics are on).")
|
|
|
|
|
|
# ---- v4 reliability ----
|
|
class SharedMetricsUpdateRunParams(ProfileParams):
|
|
"""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."""
|
|
|
|
outcome: str
|
|
failed_stage: str | None = None
|
|
mechanism: str | None = None
|
|
duration_ms: float | None = None
|
|
from_commit_date: float | None = None
|
|
|
|
|
|
class SharedMetricsUpdateRunResult(Result):
|
|
ok: bool
|
|
|
|
|
|
method("shared_metrics.update_run", params=SharedMetricsUpdateRunParams, result=SharedMetricsUpdateRunResult,
|
|
doc="Count one Desktop packaged self-update outcome (fire-and-forget; a no-op unless shared metrics are on).")
|
|
# ---- end v4 reliability ----
|
|
|
|
|
|
# ---- v5 desktop ----
|
|
class SharedMetricsDesktopFeatureUseParams(ProfileParams):
|
|
"""``area`` is a Desktop surface id (``command_palette``, ``terminal_pane``, ``settings_<view>`` …);
|
|
the backend collapses anything outside its closed set to ``other``."""
|
|
|
|
area: str
|
|
|
|
|
|
method("shared_metrics.desktop_feature_use", params=SharedMetricsDesktopFeatureUseParams,
|
|
result=OkResult,
|
|
doc="Count one Desktop area used today (fire-and-forget; once per area per UTC day; a no-op unless on).")
|
|
|
|
|
|
class SharedMetricsDesktopFrictionParams(ProfileParams):
|
|
"""``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."""
|
|
|
|
kind: str
|
|
detail: str
|
|
|
|
|
|
method("shared_metrics.desktop_friction", params=SharedMetricsDesktopFrictionParams,
|
|
result=OkResult,
|
|
doc="Count one Desktop friction event (fire-and-forget; capped per day; a no-op unless on).")
|
|
|
|
|
|
class SharedMetricsDesktopOnboardingParams(ProfileParams):
|
|
"""``step`` a Desktop first-run step id; ``event`` reached|completed|abandoned."""
|
|
|
|
step: str
|
|
event: str
|
|
|
|
|
|
method("shared_metrics.desktop_onboarding", params=SharedMetricsDesktopOnboardingParams,
|
|
result=OkResult,
|
|
doc="Count one Desktop first-run step transition (fire-and-forget; once per step+event; a no-op unless on).")
|
|
|
|
|
|
class SharedMetricsDesktopDislikeParams(ProfileParams):
|
|
"""``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)."""
|
|
|
|
signal: str
|
|
target: str = ""
|
|
setting: str | None = None
|
|
|
|
|
|
method("shared_metrics.desktop_dislike", params=SharedMetricsDesktopDislikeParams,
|
|
result=OkResult,
|
|
doc="Count one Desktop dislike signal (fire-and-forget; capped per signal per day; a no-op unless on).")
|
|
|
|
|
|
class SharedMetricsDesktopModeDay(Params):
|
|
mode: Literal["bots", "sessions"]
|
|
active_ms: float = 0
|
|
messages_sent: int = 0
|
|
|
|
|
|
class SharedMetricsDesktopActionDay(Params):
|
|
action: str
|
|
via: Literal["click", "menu", "palette", "shortcut"]
|
|
count: int
|
|
|
|
|
|
class SharedMetricsDesktopDailyParams(ProfileParams):
|
|
"""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."""
|
|
|
|
day: str
|
|
bot_count: int = 0
|
|
modes: list[SharedMetricsDesktopModeDay] = Field(default_factory=list)
|
|
actions: list[SharedMetricsDesktopActionDay] = Field(default_factory=list)
|
|
|
|
|
|
class SharedMetricsDesktopDailyResult(Result):
|
|
recorded: bool
|
|
|
|
|
|
method("shared_metrics.desktop_daily", params=SharedMetricsDesktopDailyParams,
|
|
result=SharedMetricsDesktopDailyResult,
|
|
doc="Record one finished Desktop day (mode use + button presses); recorded=false keeps it for a retry.")
|
|
# ---- end v5 desktop ----
|
|
|
|
|
|
# ── model.options ─────────────────────────────────────────────────────────────────────────────
|
|
|
|
|
|
class ModelOptionsParams(ProfileParams):
|
|
session_id: str | None = None
|
|
explicit_only: bool = False
|
|
include_unconfigured: bool = False
|
|
refresh: bool = False
|
|
|
|
|
|
# TODO(common): ModelPricing / ModelCapabilities / ModelOptionProvider are also the row shape of
|
|
# ``model.save_key``'s ``provider`` — the parent consolidates into contracts/common.py.
|
|
class ModelPricing(Result):
|
|
"""``hermes_cli/inventory.py::_apply_pricing`` — formatted $/Mtok strings (``""`` unknown,
|
|
``"free"``); the sale fields are Nous Portal-only."""
|
|
|
|
input: str
|
|
output: str
|
|
cache: str | None = None
|
|
free: bool
|
|
discount_percent: int | None = None
|
|
was_input: str | None = None
|
|
was_output: str | None = None
|
|
|
|
|
|
class ModelCapabilities(Result):
|
|
"""``hermes_cli/inventory.py::_apply_capabilities``."""
|
|
|
|
fast: bool
|
|
reasoning: bool
|
|
can_disable_reasoning: bool | None = None
|
|
|
|
|
|
class ModelOptionProvider(OpenModel):
|
|
"""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)."""
|
|
|
|
slug: str
|
|
name: str
|
|
models: list[str] = Field(default_factory=list)
|
|
total_models: int | None = None
|
|
is_current: bool | None = None
|
|
is_user_defined: bool | None = None
|
|
source: str | None = None
|
|
aliases: list[str] | None = None
|
|
api_url: str | None = None
|
|
auth_type: str | None = None
|
|
authenticated: bool | None = None
|
|
key_env: str | None = None
|
|
warning: str | None = None
|
|
featured_models: list[str] | None = None
|
|
capabilities: dict[str, ModelCapabilities] | None = None
|
|
pricing: dict[str, ModelPricing] | None = None
|
|
pricing_pending: bool | None = None
|
|
free_tier: bool | None = None
|
|
free_tier_pending: bool | None = None
|
|
free_tier_row: bool | None = None
|
|
unavailable_models: list[str] | None = None
|
|
|
|
|
|
class ModelOptionsResult(Result):
|
|
providers: list[ModelOptionProvider]
|
|
model: str = ""
|
|
provider: str = ""
|
|
|
|
|
|
method("model.options", params=ModelOptionsParams, result=ModelOptionsResult,
|
|
doc="Provider/model inventory for the picker, layered over the session's live provider when given.")
|
|
|
|
|
|
# ── image.generate ────────────────────────────────────────────────────────────────────────────
|
|
|
|
|
|
class ImageGenerateParams(Params):
|
|
prompt: str | None = None
|
|
aspect_ratio: str | None = None
|
|
probe: JsonValue | None = None # truthy word/flag: availability check only
|
|
max_bytes: int | None = None
|
|
|
|
|
|
class ImageGenerateResult(Result):
|
|
"""``probe`` answers ``{available}`` alone; ``image_data`` (data URL) is omitted when the
|
|
download failed or exceeded ``max_bytes`` so callers fall back to ``image``."""
|
|
|
|
available: bool
|
|
success: bool | None = None
|
|
image: str | None = None
|
|
image_data: str | None = None
|
|
error: str | None = None
|
|
|
|
|
|
method("image.generate", params=ImageGenerateParams, result=ImageGenerateResult,
|
|
doc="Generate an image through the tool's provider dispatcher and hand the renderer a data URL.")
|
|
|
|
|
|
# ── session.control ───────────────────────────────────────────────────────────────────────────
|
|
|
|
|
|
class GoalContractSnapshot(Result):
|
|
"""``hermes_cli/goals.py::GoalContract.to_dict``."""
|
|
|
|
outcome: str = ""
|
|
verification: str = ""
|
|
constraints: str = ""
|
|
boundaries: str = ""
|
|
stop_when: str = ""
|
|
|
|
|
|
class GoalGateSnapshot(Result):
|
|
command: str
|
|
timeout_seconds: int
|
|
max_retries: int
|
|
attempts: int
|
|
last_exit_code: int | None = None
|
|
|
|
|
|
class WaitBarrierUntil(Result):
|
|
type: Literal["until"]
|
|
until_at: float
|
|
reason: str = ""
|
|
|
|
|
|
class WaitBarrierTarget(Result):
|
|
type: Literal["session", "pid"]
|
|
target: str | int
|
|
reason: str = ""
|
|
|
|
|
|
class GoalSnapshot(Result):
|
|
"""``methods_session_control.py::_safe_goal_snapshot`` — the frontend-safe GoalState subset."""
|
|
|
|
title: str
|
|
status: str
|
|
turns_used: int
|
|
max_turns: int
|
|
contract: GoalContractSnapshot
|
|
subgoals: list[str]
|
|
gates: list[GoalGateSnapshot]
|
|
created_at: float | None = None
|
|
updated_at: float | None = None
|
|
paused_reason: str | None = None
|
|
last_verdict: str | None = None
|
|
last_reason: str | None = None
|
|
wait_barrier: WaitBarrierUntil | WaitBarrierTarget | None = Field(default=None, discriminator="type")
|
|
|
|
|
|
class LoopSnapshot(Result):
|
|
"""``_safe_loop_snapshot`` — persisted LoopState fields, never its route."""
|
|
|
|
prompt: str
|
|
status: str
|
|
mode: str
|
|
interval_seconds: float
|
|
current_delay: float
|
|
times: int
|
|
until: str
|
|
max_ticks: int
|
|
ticks_fired: int
|
|
created_at: float
|
|
last_fired_at: float
|
|
next_due_at: float
|
|
awaiting_response: bool
|
|
deferred_by_goal: bool
|
|
paused_reason: str | None = None
|
|
last_stop_reason: str | None = None
|
|
|
|
|
|
class HeartbeatSnapshot(Result):
|
|
prompt: str
|
|
status: str
|
|
interval_seconds: int
|
|
created_at: float
|
|
last_fired_at: float
|
|
fire_count: int
|
|
|
|
|
|
class SessionControlSnapshot(Result):
|
|
"""``_snapshot_control`` — ``revision`` is a hash of the visible state (``""`` when empty);
|
|
``updated_at`` is the newest persisted timestamp (``0`` when none)."""
|
|
|
|
goal: GoalSnapshot | None
|
|
loop: LoopSnapshot | None
|
|
heartbeat: HeartbeatSnapshot | None
|
|
revision: str
|
|
updated_at: float
|
|
|
|
|
|
class SessionControlReadParams(ProfileParams):
|
|
session_id: str
|
|
|
|
|
|
class SessionControlReadResult(Result):
|
|
control: SessionControlSnapshot
|
|
|
|
|
|
method("session.control.read", params=SessionControlReadParams, result=SessionControlReadResult,
|
|
doc="Stable, allowlisted snapshot of one live session's goal / loop / heartbeat state.")
|
|
|
|
|
|
class SessionControlAction(WireEnum):
|
|
goal_pause = "goal.pause"
|
|
goal_resume = "goal.resume"
|
|
goal_clear = "goal.clear"
|
|
goal_unwait = "goal.unwait"
|
|
loop_pause = "loop.pause"
|
|
loop_resume = "loop.resume"
|
|
loop_stop = "loop.stop"
|
|
subgoal_add = "subgoal.add"
|
|
subgoal_remove = "subgoal.remove"
|
|
subgoal_clear = "subgoal.clear"
|
|
heartbeat_pause = "heartbeat.pause"
|
|
heartbeat_resume = "heartbeat.resume"
|
|
heartbeat_clear = "heartbeat.clear"
|
|
|
|
|
|
class SessionControlArgs(Params):
|
|
"""``subgoal.add`` reads ``text``; ``subgoal.remove`` reads the 1-based ``index``."""
|
|
|
|
text: str | None = None
|
|
index: int | None = None
|
|
|
|
|
|
class SessionControlParams(ProfileParams):
|
|
"""``action`` is validated by the handler (unknown / gate actions answer ``4004``), so it stays a
|
|
string on the wire; ``SessionControlAction`` lists the accepted set."""
|
|
|
|
session_id: str
|
|
action: str
|
|
args: SessionControlArgs | None = None
|
|
|
|
|
|
class SessionControlDispatch(Result):
|
|
"""``_dispatch_envelope`` — the command result's user-visible envelope, every key always present."""
|
|
|
|
type: str | None
|
|
output: str | None
|
|
notice: str | None
|
|
message: str | None
|
|
display: str | None
|
|
|
|
|
|
class SessionControlResult(Result):
|
|
control: SessionControlSnapshot
|
|
dispatch: SessionControlDispatch
|
|
|
|
|
|
method("session.control", params=SessionControlParams, result=SessionControlResult,
|
|
doc="Run one allowlisted goal / loop / subgoal / heartbeat action and return the exact resulting snapshot.")
|
|
|
|
|
|
# ── verification.status ───────────────────────────────────────────────────────────────────────
|
|
|
|
|
|
class VerificationStatusParams(ProfileParams):
|
|
session_id: str | None = None
|
|
session_key: str | None = None
|
|
cwd: str | None = None
|
|
|
|
|
|
class VerificationEvidenceRow(OpenModel):
|
|
"""One ``verification_events`` row (``agent/verification_evidence.py``)."""
|
|
|
|
id: int | None = None
|
|
created_at: str | None = None
|
|
session_id: str | None = None
|
|
cwd: str | None = None
|
|
root: str | None = None
|
|
command: str | None = None
|
|
canonical_command: str | None = None
|
|
kind: str | None = None
|
|
scope: str | None = None
|
|
status: str | None = None
|
|
exit_code: int | None = None
|
|
output_summary: str | None = None
|
|
|
|
|
|
class VerificationStatusInfo(Result):
|
|
"""``verification_status()``: ``disabled`` / ``not_applicable`` / ``unverified`` / ``stale`` or the
|
|
latest event's own status; ``root`` and friends only once a workspace was identified."""
|
|
|
|
status: str
|
|
evidence: VerificationEvidenceRow | None = None
|
|
root: str | None = None
|
|
session_id: str | None = None
|
|
changed_paths: list[str] | None = None
|
|
|
|
|
|
class VerificationStatusResult(Result):
|
|
verification: VerificationStatusInfo
|
|
|
|
|
|
method("verification.status", params=VerificationStatusParams, result=VerificationStatusResult,
|
|
doc="Best known verification evidence for a cwd/session; read-only, never runs checks.")
|