hypercli-sdk 2026.7.31__tar.gz → 2026.8.11__tar.gz

{hypercli_sdk-2026.7.31 → hypercli_sdk-2026.8.11}/.gitignore

@@ -30,6 +30,8 @@ coverage
 .agents/
 .opencode/
 .github/
+/skills/
+/skills-lock.json
 docs/agent-display-names.md
 *.pem
 

{hypercli_sdk-2026.7.31 → hypercli_sdk-2026.8.11}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: hypercli-sdk
-Version: 2026.7.31
+Version: 2026.8.11
 Summary: Python SDK for HyperCLI - GPU orchestration and HyperAgent API
 Project-URL: Homepage, https://hypercli.com
 Project-URL: Documentation, https://docs.hypercli.com
@@ -122,7 +122,7 @@ the HyperClaw inference base URL for chat completions:
 from hypercli import HyperCLI
 from openai import OpenAI
 
-sdk = HyperCLI(api_key="hyper_api_key", agent_api_key="sk-agent")
+sdk = HyperCLI(api_key="hyper_api_key", agent_api_key="hyper_api_agent_key")
 plans = sdk.agent.plans()
 activation = sdk.agent.redeem_grant_code("PROMO123")
 renewal = sdk.agent.redeem_grant_code("PROMO123", extend_existing=True)
@@ -140,9 +140,23 @@ response = client.chat.completions.create(
 
 `redeem_grant_code()` applies a promo/activation code to the current HyperClaw account and returns the created entitlement. Codes create new entitlements by default; pass `extend_existing=True` only for renewal/extension behavior.
 
+Plan IDs are open strings on the wire so future and historical plans continue
+to parse. `plan.canonical_id` recognizes the current `solo`, `team`, and `pro`
+IDs. Plan access comes from the HyperClaw summary, including direct grants:
+
+```python
+summary = sdk.agent.subscription_summary()
+if summary.has_active_plan:  # active subscription OR direct entitlement
+    print(summary.agent_slots)
+```
+
+Do not substitute the Orchestra `/api/auth/me` subscription flag. If the
+summary request returns `401` or `403`, the selected key cannot establish plan
+state; treat it as unknown rather than as no plan.
+
 ## OpenClaw Agents
 
-OpenClaw uses the generic deployment launch surface. `registry_url`, `registry_auth`, `sync_root`, and `sync_enabled` are generic deployment options; the OpenClaw helpers only add defaults such as routes, image, and `sync_root=/home/node`.
+OpenClaw uses the generic deployment launch surface. `registry_url`, `registry_auth`, and `sync_root` are generic deployment options. A nonblank `sync_root` enables Reef persistence; no separate `sync_enabled` field is serialized. The OpenClaw helpers add defaults such as routes, image, and `sync_root=/home/node`.
 
 ```python
 agent = client.deployments.create_openclaw(
@@ -151,8 +165,58 @@ agent = client.deployments.create_openclaw(
     registry_url="git.nedos.co",
     registry_auth={"username": "ci", "password": "token"},
 )
+agent = client.deployments.wait_running(agent.id, timeout=300)
+
+capacity = client.deployments.list_with_capacity()
+print(capacity.max_agents_per_account, capacity.running_agents)
+for slot in capacity.agent_slots:
+    print(slot.size, slot.plan_id, slot.agent_id)
 ```
 
+`list()` remains the compatibility list of agents. `list_with_capacity()`
+preserves the full deployment envelope: saved/running account limits, pooled
+TPD, aggregate slot inventory, and individual entitlement-backed agent slots.
+
+For a long-lived UI, subscribe to thin invalidations and refresh REST in the
+handler:
+
+```python
+import asyncio
+
+async def changed(_event):
+    agents = await asyncio.to_thread(client.deployments.list)
+    render(agents)
+
+async def snapshot():
+    agents = await asyncio.to_thread(client.deployments.list)
+    render(agents)
+
+stop = asyncio.Event()
+await client.deployments.subscribe(changed, stop_event=stop, on_ready=snapshot)
+```
+
+The `on_ready` callback runs after user-stream authentication and before event
+frames are read; it repeats after reconnect so no transition can slip
+between snapshot and subscription. Transition events carry `agent_id` for
+local filtering plus `state`, `reason`, `error`, and `message`, but are not
+resource snapshots and may be duplicated or coalesced; refresh REST for
+authority.
+
+Managed-agent lifecycle snapshots currently use `CREATING`, `STARTING`,
+`RESTORING`, `RUNNING`, `STOPPING`, `STOPPED`, `ARCHIVING`, `ARCHIVED`,
+`FAILED`, and `DELETED`. `CREATING` is fresh admission, `STARTING` resumes a
+warm retained agent, and `RESTORING` hydrates a cold agent from its exact
+archive checkpoint. `STOPPED` retains warm local storage. `ARCHIVING` is the
+public transition to verified cold storage.
+`ARCHIVED` is the Backend-persisted cold-restorable terminal projection after
+Lagoon drops its agent task, namespace, PVC, and local S3 copy. `DELETED` is a
+Backend-only terminal state and normally hidden from user lists. State values
+remain open strings; use REST as authority instead of
+recreating the server lifecycle machine in the client. Each snapshot may also
+carry open-string diagnostics: `reason` is the stable cause such as `start`,
+`api_stop`, `runtime_exit`, `timeout`, or `delete`, `error` is a failure code
+when the transition failed, and `message` is human-readable context.
+
 Use `create_openclaw_pro(...)` for the desktop/browser image. It enables noVNC through the protected `desktop-<agent>.hypercli.app` route and sets `OPENCLAW_DESKTOP_ENABLED=1`.
 
 `heartbeat` maps directly to upstream OpenClaw config at `config.agents.defaults.heartbeat`. Omit it to keep upstream defaults, or pass values such as `heartbeat={"every": "1h", "target": "last"}`.
@@ -161,13 +225,22 @@ Automatic memory indexing is off by default. Opt in with `memory_index={"on_sess
 
 ## Hosted Coding Agents
 
-OpenCode, Codex, Claude Code, Goose, and Kimi Code use canonical Reef images.
+Native Buzz Agent, OpenCode, Codex, Claude Code, Goose, and Kimi Code use
+canonical managed-runtime images.
 They have no public runtime port: lifecycle, exec, shell, workspace sync, and
 authentication all use the existing authenticated deployment APIs. OpenCode
 and Goose default to HyperCLI's Anthropic-native `kimi-k2.6-anthropic` route.
 Kimi Code keeps Moonshot's upstream device login and service.
+Claude Code, Codex, and Kimi Code are native-login-first. For Buzz-managed
+launches, `HYPERCLI_RUNTIME_INFERENCE=hypercli` is an explicit compatibility
+switch for Claude and Kimi. The gateway now exposes `/v1/responses`, and Buzz
+compatibility mode renders Codex with `wire_api="responses"`; a successful
+HyperCLI-model Codex Responses E2E remains unvalidated, so that path is not yet
+advertised as supported. See the
+[runtime and persistence matrix](../docs/agents/coding-runtimes.mdx).
 
 ```python
+buzz_agent = client.deployments.create_buzz_agent(name="buzz-agent")
 agent = client.deployments.create_opencode(name="opencode")
 codex = client.deployments.create_codex(name="codex")
 claude = client.deployments.create_claude_code(name="claude")
@@ -183,10 +256,19 @@ async with await codex.auth.login("device") as login:
 ```
 
 The login helper opens a short-lived, agent-bound shell WebSocket and runs the
-runtime's native login command inside the Reef pod. It never puts an API key on
+runtime's native login command inside the managed runtime. It never puts an API key on
 the command line. Runtime credentials and state live under the persistent
 `/home/node` sync root.
 
+Authentication is runtime-specific rather than one universal login protocol.
+Native Buzz Agent has no separate login step and uses its injected model and
+provider configuration. OpenCode combines adapter discovery with its
+interactive provider login; Codex
+adds native device login; Claude Code exposes Claude.ai, Console, and SSO;
+Goose uses its injected deployment credential; and Kimi Code uses the
+upstream adapter's methods. Goose and Kimi Code do not expose a noninteractive
+logout command through this SDK surface.
+
 The images default to a long-lived direct shell/exec container. A Buzz provider
 launches one for a Buzz-managed identity with the typed launch contract:
 
@@ -195,7 +277,6 @@ from hypercli import BuzzLaunchConfig
 
 agent = client.deployments.create_opencode(
     name="buzz-opencode",
-    env={"HYPER_API_KEY": inference_key},
     buzz=BuzzLaunchConfig(
         private_key_nsec=agent_nsec,
         relay_url=relay_url,
@@ -205,15 +286,25 @@ agent = client.deployments.create_opencode(
 )
 ```
 
+The managed platform injects an agent-scoped `HYPER_AGENTS_API_KEY` into the
+runtime. Do not copy an account API key into the launch environment.
+
 The SDK selects `/usr/local/bin/buzz-acp`, the runtime-specific child ACP
 command and arguments, the hosted Buzz MCP command, lazy pool creation, relay
-observation, and persistent `/home/node` settings. Buzz-reserved environment
-keys are rendered from the typed object after caller environment values.
+observation, and persistent `/home/node` settings. `/home/node/shared`
+remains reserved for Workspace projections; the specialized image reconciles
+the Buzz nest after the home mount and runs the harness from
+`/home/node/.buzz`. OpenCode and Codex read its canonical `AGENTS.md`, while
+Claude Code receives `CLAUDE.md -> AGENTS.md`. `base_prompt.md` stays compiled
+into `buzz-acp`. Buzz-reserved environment keys are rendered from the typed
+object after caller environment values.
 `buzz_enabled=True` remains as a deprecated raw-environment compatibility path.
 Typed and compatibility Buzz launches select the matching `hypercli-buzz`
-image family (`opencode`, `codex`, `claude`, `goose`, or `kimi-code`) by
+image family (`buzz-agent`, `opencode`, `codex`, `claude`, `goose`, or
+`kimi-code`) by
 default. Ordinary coding-agent helpers without Buzz keep the generic
-`ghcr.io/hypercli/hypercli-<runtime>:latest` default. An explicit `image=`
+`ghcr.io/hypercli/hypercli-<runtime>:latest` default, except native Buzz Agent,
+whose runtime image is already `hypercli-buzz-agent`. An explicit `image=`
 continues to override either default.
 
 Direct `BuzzLaunchConfig` renders timeout and response-policy values but does
@@ -222,18 +313,22 @@ are rejected later by `buzz-acp`. The Desktop provider also maps structured
 Goose model/provider fields to `GOOSE_MODEL`/`GOOSE_PROVIDER`; direct Python
 SDK callers must set any Goose-specific environment themselves.
 
-Buzz launches require `size="large"`; ordinary coding-agent helpers preserve a
-caller-provided size or the backend default. Stock Buzz provider agents do not
+Buzz launches leave size unset for live backend/provider slot selection;
+ordinary coding-agent helpers preserve a caller-provided size or the backend
+default. Stock Buzz provider agents do not
 start on app launch and the current provider protocol has no stop callback.
 Editing a running agent does not replace its HyperCLI launch environment: stop
 the deployment through the authenticated HyperCLI API and deploy it again from
-Buzz to apply changes. Desktop's best-effort `!shutdown` chat control may exit
-the harness, but it does not stop or release the HyperCLI deployment.
+Buzz to apply changes. A successfully delivered and accepted `!shutdown` can
+exit a new `restart=False` launch; the hosted terminal-state observer then
+reports `stopping`, completes runtime cleanup, marks the deployment `stopped`,
+and releases its slot. Desktop receives no provider acknowledgement and keeps
+its local deployed record.
 
 Stock Buzz expects ACP NDJSON. It skips non-JSON child stdout, and
 `agent_message_chunk` is activity telemetry rather than a channel reply. There
 is no plaintext fallback; a visible reply requires the agent to invoke the Buzz
-send command/tool. The five-runtime SDK coverage validates request rendering,
+send command/tool. The six-runtime SDK coverage validates request rendering,
 not live launches.
 
 The agent nsec and caller environment become raw deployment environment values.

{hypercli_sdk-2026.7.31 → hypercli_sdk-2026.8.11}/README.md

@@ -87,7 +87,7 @@ the HyperClaw inference base URL for chat completions:
 from hypercli import HyperCLI
 from openai import OpenAI
 
-sdk = HyperCLI(api_key="hyper_api_key", agent_api_key="sk-agent")
+sdk = HyperCLI(api_key="hyper_api_key", agent_api_key="hyper_api_agent_key")
 plans = sdk.agent.plans()
 activation = sdk.agent.redeem_grant_code("PROMO123")
 renewal = sdk.agent.redeem_grant_code("PROMO123", extend_existing=True)
@@ -105,9 +105,23 @@ response = client.chat.completions.create(
 
 `redeem_grant_code()` applies a promo/activation code to the current HyperClaw account and returns the created entitlement. Codes create new entitlements by default; pass `extend_existing=True` only for renewal/extension behavior.
 
+Plan IDs are open strings on the wire so future and historical plans continue
+to parse. `plan.canonical_id` recognizes the current `solo`, `team`, and `pro`
+IDs. Plan access comes from the HyperClaw summary, including direct grants:
+
+```python
+summary = sdk.agent.subscription_summary()
+if summary.has_active_plan:  # active subscription OR direct entitlement
+    print(summary.agent_slots)
+```
+
+Do not substitute the Orchestra `/api/auth/me` subscription flag. If the
+summary request returns `401` or `403`, the selected key cannot establish plan
+state; treat it as unknown rather than as no plan.
+
 ## OpenClaw Agents
 
-OpenClaw uses the generic deployment launch surface. `registry_url`, `registry_auth`, `sync_root`, and `sync_enabled` are generic deployment options; the OpenClaw helpers only add defaults such as routes, image, and `sync_root=/home/node`.
+OpenClaw uses the generic deployment launch surface. `registry_url`, `registry_auth`, and `sync_root` are generic deployment options. A nonblank `sync_root` enables Reef persistence; no separate `sync_enabled` field is serialized. The OpenClaw helpers add defaults such as routes, image, and `sync_root=/home/node`.
 
 ```python
 agent = client.deployments.create_openclaw(
@@ -116,8 +130,58 @@ agent = client.deployments.create_openclaw(
     registry_url="git.nedos.co",
     registry_auth={"username": "ci", "password": "token"},
 )
+agent = client.deployments.wait_running(agent.id, timeout=300)
+
+capacity = client.deployments.list_with_capacity()
+print(capacity.max_agents_per_account, capacity.running_agents)
+for slot in capacity.agent_slots:
+    print(slot.size, slot.plan_id, slot.agent_id)
 ```
 
+`list()` remains the compatibility list of agents. `list_with_capacity()`
+preserves the full deployment envelope: saved/running account limits, pooled
+TPD, aggregate slot inventory, and individual entitlement-backed agent slots.
+
+For a long-lived UI, subscribe to thin invalidations and refresh REST in the
+handler:
+
+```python
+import asyncio
+
+async def changed(_event):
+    agents = await asyncio.to_thread(client.deployments.list)
+    render(agents)
+
+async def snapshot():
+    agents = await asyncio.to_thread(client.deployments.list)
+    render(agents)
+
+stop = asyncio.Event()
+await client.deployments.subscribe(changed, stop_event=stop, on_ready=snapshot)
+```
+
+The `on_ready` callback runs after user-stream authentication and before event
+frames are read; it repeats after reconnect so no transition can slip
+between snapshot and subscription. Transition events carry `agent_id` for
+local filtering plus `state`, `reason`, `error`, and `message`, but are not
+resource snapshots and may be duplicated or coalesced; refresh REST for
+authority.
+
+Managed-agent lifecycle snapshots currently use `CREATING`, `STARTING`,
+`RESTORING`, `RUNNING`, `STOPPING`, `STOPPED`, `ARCHIVING`, `ARCHIVED`,
+`FAILED`, and `DELETED`. `CREATING` is fresh admission, `STARTING` resumes a
+warm retained agent, and `RESTORING` hydrates a cold agent from its exact
+archive checkpoint. `STOPPED` retains warm local storage. `ARCHIVING` is the
+public transition to verified cold storage.
+`ARCHIVED` is the Backend-persisted cold-restorable terminal projection after
+Lagoon drops its agent task, namespace, PVC, and local S3 copy. `DELETED` is a
+Backend-only terminal state and normally hidden from user lists. State values
+remain open strings; use REST as authority instead of
+recreating the server lifecycle machine in the client. Each snapshot may also
+carry open-string diagnostics: `reason` is the stable cause such as `start`,
+`api_stop`, `runtime_exit`, `timeout`, or `delete`, `error` is a failure code
+when the transition failed, and `message` is human-readable context.
+
 Use `create_openclaw_pro(...)` for the desktop/browser image. It enables noVNC through the protected `desktop-<agent>.hypercli.app` route and sets `OPENCLAW_DESKTOP_ENABLED=1`.
 
 `heartbeat` maps directly to upstream OpenClaw config at `config.agents.defaults.heartbeat`. Omit it to keep upstream defaults, or pass values such as `heartbeat={"every": "1h", "target": "last"}`.
@@ -126,13 +190,22 @@ Automatic memory indexing is off by default. Opt in with `memory_index={"on_sess
 
 ## Hosted Coding Agents
 
-OpenCode, Codex, Claude Code, Goose, and Kimi Code use canonical Reef images.
+Native Buzz Agent, OpenCode, Codex, Claude Code, Goose, and Kimi Code use
+canonical managed-runtime images.
 They have no public runtime port: lifecycle, exec, shell, workspace sync, and
 authentication all use the existing authenticated deployment APIs. OpenCode
 and Goose default to HyperCLI's Anthropic-native `kimi-k2.6-anthropic` route.
 Kimi Code keeps Moonshot's upstream device login and service.
+Claude Code, Codex, and Kimi Code are native-login-first. For Buzz-managed
+launches, `HYPERCLI_RUNTIME_INFERENCE=hypercli` is an explicit compatibility
+switch for Claude and Kimi. The gateway now exposes `/v1/responses`, and Buzz
+compatibility mode renders Codex with `wire_api="responses"`; a successful
+HyperCLI-model Codex Responses E2E remains unvalidated, so that path is not yet
+advertised as supported. See the
+[runtime and persistence matrix](../docs/agents/coding-runtimes.mdx).
 
 ```python
+buzz_agent = client.deployments.create_buzz_agent(name="buzz-agent")
 agent = client.deployments.create_opencode(name="opencode")
 codex = client.deployments.create_codex(name="codex")
 claude = client.deployments.create_claude_code(name="claude")
@@ -148,10 +221,19 @@ async with await codex.auth.login("device") as login:
 ```
 
 The login helper opens a short-lived, agent-bound shell WebSocket and runs the
-runtime's native login command inside the Reef pod. It never puts an API key on
+runtime's native login command inside the managed runtime. It never puts an API key on
 the command line. Runtime credentials and state live under the persistent
 `/home/node` sync root.
 
+Authentication is runtime-specific rather than one universal login protocol.
+Native Buzz Agent has no separate login step and uses its injected model and
+provider configuration. OpenCode combines adapter discovery with its
+interactive provider login; Codex
+adds native device login; Claude Code exposes Claude.ai, Console, and SSO;
+Goose uses its injected deployment credential; and Kimi Code uses the
+upstream adapter's methods. Goose and Kimi Code do not expose a noninteractive
+logout command through this SDK surface.
+
 The images default to a long-lived direct shell/exec container. A Buzz provider
 launches one for a Buzz-managed identity with the typed launch contract:
 
@@ -160,7 +242,6 @@ from hypercli import BuzzLaunchConfig
 
 agent = client.deployments.create_opencode(
     name="buzz-opencode",
-    env={"HYPER_API_KEY": inference_key},
     buzz=BuzzLaunchConfig(
         private_key_nsec=agent_nsec,
         relay_url=relay_url,
@@ -170,15 +251,25 @@ agent = client.deployments.create_opencode(
 )
 ```
 
+The managed platform injects an agent-scoped `HYPER_AGENTS_API_KEY` into the
+runtime. Do not copy an account API key into the launch environment.
+
 The SDK selects `/usr/local/bin/buzz-acp`, the runtime-specific child ACP
 command and arguments, the hosted Buzz MCP command, lazy pool creation, relay
-observation, and persistent `/home/node` settings. Buzz-reserved environment
-keys are rendered from the typed object after caller environment values.
+observation, and persistent `/home/node` settings. `/home/node/shared`
+remains reserved for Workspace projections; the specialized image reconciles
+the Buzz nest after the home mount and runs the harness from
+`/home/node/.buzz`. OpenCode and Codex read its canonical `AGENTS.md`, while
+Claude Code receives `CLAUDE.md -> AGENTS.md`. `base_prompt.md` stays compiled
+into `buzz-acp`. Buzz-reserved environment keys are rendered from the typed
+object after caller environment values.
 `buzz_enabled=True` remains as a deprecated raw-environment compatibility path.
 Typed and compatibility Buzz launches select the matching `hypercli-buzz`
-image family (`opencode`, `codex`, `claude`, `goose`, or `kimi-code`) by
+image family (`buzz-agent`, `opencode`, `codex`, `claude`, `goose`, or
+`kimi-code`) by
 default. Ordinary coding-agent helpers without Buzz keep the generic
-`ghcr.io/hypercli/hypercli-<runtime>:latest` default. An explicit `image=`
+`ghcr.io/hypercli/hypercli-<runtime>:latest` default, except native Buzz Agent,
+whose runtime image is already `hypercli-buzz-agent`. An explicit `image=`
 continues to override either default.
 
 Direct `BuzzLaunchConfig` renders timeout and response-policy values but does
@@ -187,18 +278,22 @@ are rejected later by `buzz-acp`. The Desktop provider also maps structured
 Goose model/provider fields to `GOOSE_MODEL`/`GOOSE_PROVIDER`; direct Python
 SDK callers must set any Goose-specific environment themselves.
 
-Buzz launches require `size="large"`; ordinary coding-agent helpers preserve a
-caller-provided size or the backend default. Stock Buzz provider agents do not
+Buzz launches leave size unset for live backend/provider slot selection;
+ordinary coding-agent helpers preserve a caller-provided size or the backend
+default. Stock Buzz provider agents do not
 start on app launch and the current provider protocol has no stop callback.
 Editing a running agent does not replace its HyperCLI launch environment: stop
 the deployment through the authenticated HyperCLI API and deploy it again from
-Buzz to apply changes. Desktop's best-effort `!shutdown` chat control may exit
-the harness, but it does not stop or release the HyperCLI deployment.
+Buzz to apply changes. A successfully delivered and accepted `!shutdown` can
+exit a new `restart=False` launch; the hosted terminal-state observer then
+reports `stopping`, completes runtime cleanup, marks the deployment `stopped`,
+and releases its slot. Desktop receives no provider acknowledgement and keeps
+its local deployed record.
 
 Stock Buzz expects ACP NDJSON. It skips non-JSON child stdout, and
 `agent_message_chunk` is activity telemetry rather than a channel reply. There
 is no plaintext fallback; a visible reply requires the agent to invoke the Buzz
-send command/tool. The five-runtime SDK coverage validates request rendering,
+send command/tool. The six-runtime SDK coverage validates request rendering,
 not live launches.
 
 The agent nsec and caller environment become raw deployment environment values.

{hypercli_sdk-2026.7.31 → hypercli_sdk-2026.8.11}/hypercli/__init__.py

@@ -14,6 +14,8 @@ from .config import (
     DEFAULT_AGENTS_WS_URL,
     DEV_AGENTS_API_BASE_URL,
     DEV_AGENTS_WS_URL,
+    get_api_key,
+    get_agent_api_key,
     get_api_url,
     get_ws_url,
     get_agents_api_base_url,
@@ -38,6 +40,7 @@ from .renders import Render, RenderStatus
 from .voice import VoiceAPI
 from .voice_stream import VoiceChunk, VoiceSession, VoiceStreamError
 from .models import Model, ModelsAPI
+from .keys import ApiKey, KeysAPI, issue_api_key_from_jwt
 from .workspaces import (
     DownloadUrl,
     Workspace,
@@ -56,17 +59,34 @@ from .user import AuthMe, RuntimeIdentity, User, UserAPI
 from .job import BaseJob, ComfyUIJob, GradioJob, apply_params, apply_graph_modes, find_node, find_nodes, load_template, graph_to_api, expand_subgraphs, DEFAULT_OBJECT_INFO
 from .logs import LogStream, stream_logs, fetch_logs
 from .agents import (
+    AGENT_RUNTIME_INACTIVE_STATES,
+    AGENT_TRANSITIONAL_STATES,
+    AGENT_WAIT_RUNNING_FAILURE_STATES,
     Agent,
+    AgentCapacity,
     AgentFileSource,
+    AgentRouteConfig,
+    AgentRoutes,
+    AgentSlot,
+    AgentSlotInventory,
+    BuzzAgent,
     BuzzLaunchConfig,
+    CANONICAL_AGENT_STATES,
     ClaudeCodeAgent,
     CodingAgent,
     CodexAgent,
+    DEFAULT_AGENT_RUNTIME_SCOPES,
+    DEFAULT_BUZZ_AGENT_IMAGE,
     DEFAULT_BUZZ_CODING_AGENT_IMAGES,
+    DEFAULT_HERMES_AGENT_IMAGE,
+    DEFAULT_HERMES_AGENT_SYNC_ROOT,
     DEFAULT_CODING_AGENT_IMAGES,
+    DEFAULT_CODING_AGENT_SYNC_INCLUDES,
+    DeploymentEvent,
     Deployments,
     ExecResult,
     GooseAgent,
+    HermesAgent,
     KimiCodeAgent,
     OpenClawAgent,
     OpenClawFileSource,
@@ -76,20 +96,44 @@ from .agents import (
     RuntimeAuthMethod,
     RuntimeAuthStatus,
     RuntimeLoginSession,
+    build_agent_config,
     build_browser_desktop_url,
+    build_hermes_agent_routes,
     build_openclaw_memory_index_env,
     build_openclaw_routes,
     build_openclaw_workspaces_sync_env,
+    is_agent_runtime_inactive_state,
+    is_agent_transitional_state,
+)
+from .hermes import (
+    HermesAPIError,
+    HermesApiClient,
+    HermesCapabilities,
+    HermesDetailedHealth,
+    HermesHealth,
+    HermesMessage,
+    HermesMessageList,
+    HermesModel,
+    HermesModels,
+    HermesRun,
+    HermesSSEEvent,
+    HermesSession,
+    HermesSessionEnvelope,
+    HermesSessionList,
+    HermesSessionModelLock,
 )
 from .shell import ShellSession, shell_connect
 from .agent import (
     HyperAgent,
+    HyperAgentCanonicalPlanId,
     HyperAgentPlan,
     HyperAgentCurrentPlan,
     HyperAgentEntitlements,
     HyperAgentEntitlementsSummary,
     HyperAgentSubscription,
+    HyperAgentSubscriptionMutationResult,
     HyperAgentSubscriptionSummary,
+    HyperAgentSubscriptionTrial,
     HyperAgentModel,
     HyperAgentUsageSummary,
     HyperAgentUsageHistoryEntry,
@@ -109,6 +153,7 @@ from .agent import (
     HyperAgentPaymentsResponse,
     HyperAgentStripeCheckoutResponse,
     HyperAgentX402CheckoutResponse,
+    parse_hyper_agent_plan_id,
 )
 from .gateway import (
     GatewayClient,
@@ -121,15 +166,20 @@ from .gateway import (
     extract_gateway_chat_tool_calls,
     normalize_gateway_chat_message,
 )
-__version__ = "2026.7.31"
+__version__ = "2026.8.11"
 __all__ = [
     "HyperCLI",
     "configure",
+    "get_api_key",
+    "get_agent_api_key",
     "get_api_url",
     "get_ws_url",
     "get_agents_api_base_url",
     "get_agents_ws_url",
     "APIError",
+    "ApiKey",
+    "KeysAPI",
+    "issue_api_key_from_jwt",
     # Images
     "GHCR_IMAGES",
     "COMFYUI_IMAGE",
@@ -209,17 +259,36 @@ __all__ = [
     "stream_logs",
     "fetch_logs",
     # Agents (Reef Pods)
+    "CANONICAL_AGENT_STATES",
+    "AGENT_TRANSITIONAL_STATES",
+    "AGENT_RUNTIME_INACTIVE_STATES",
+    "AGENT_WAIT_RUNNING_FAILURE_STATES",
+    "is_agent_transitional_state",
+    "is_agent_runtime_inactive_state",
     "Deployments",
+    "DeploymentEvent",
     "Agent",
+    "AgentCapacity",
     "AgentFileSource",
+    "AgentRouteConfig",
+    "AgentRoutes",
+    "AgentSlot",
+    "AgentSlotInventory",
+    "BuzzAgent",
     "BuzzLaunchConfig",
     "CodingAgent",
+    "DEFAULT_AGENT_RUNTIME_SCOPES",
+    "DEFAULT_BUZZ_AGENT_IMAGE",
     "DEFAULT_CODING_AGENT_IMAGES",
+    "DEFAULT_CODING_AGENT_SYNC_INCLUDES",
     "DEFAULT_BUZZ_CODING_AGENT_IMAGES",
+    "DEFAULT_HERMES_AGENT_IMAGE",
+    "DEFAULT_HERMES_AGENT_SYNC_ROOT",
     "OpenCodeAgent",
     "CodexAgent",
     "ClaudeCodeAgent",
     "GooseAgent",
+    "HermesAgent",
     "KimiCodeAgent",
     "OpenClawAgent",
     "OpenClawFileSource",
@@ -229,21 +298,42 @@ __all__ = [
     "RuntimeAuthStatus",
     "RuntimeLoginSession",
     "ExecResult",
+    "build_agent_config",
     "build_browser_desktop_url",
+    "build_hermes_agent_routes",
     "build_openclaw_routes",
     "build_openclaw_memory_index_env",
     "build_openclaw_workspaces_sync_env",
+    # Hermes API Server
+    "HermesAPIError",
+    "HermesApiClient",
+    "HermesCapabilities",
+    "HermesDetailedHealth",
+    "HermesHealth",
+    "HermesMessage",
+    "HermesMessageList",
+    "HermesModel",
+    "HermesModels",
+    "HermesRun",
+    "HermesSSEEvent",
+    "HermesSession",
+    "HermesSessionEnvelope",
+    "HermesSessionList",
+    "HermesSessionModelLock",
     # Shell
     "ShellSession",
     "shell_connect",
     # HyperAgent
     "HyperAgent",
+    "HyperAgentCanonicalPlanId",
     "HyperAgentPlan",
     "HyperAgentCurrentPlan",
     "HyperAgentEntitlements",
     "HyperAgentEntitlementsSummary",
     "HyperAgentSubscription",
+    "HyperAgentSubscriptionMutationResult",
     "HyperAgentSubscriptionSummary",
+    "HyperAgentSubscriptionTrial",
     "HyperAgentModel",
     "HyperAgentUsageSummary",
     "HyperAgentUsageHistoryEntry",
@@ -263,6 +353,7 @@ __all__ = [
     "HyperAgentPaymentsResponse",
     "HyperAgentStripeCheckoutResponse",
     "HyperAgentX402CheckoutResponse",
+    "parse_hyper_agent_plan_id",
     # OpenClaw Gateway
     "GatewayClient",
     "GatewayError",