hypercli-sdk 0.11.0__tar.gz → 0.11.2__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (83) hide show
  1. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/PKG-INFO +12 -1
  2. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/README.md +11 -0
  3. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/hypercli/__init__.py +11 -2
  4. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/hypercli/agents.py +115 -7
  5. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/hypercli/client.py +3 -1
  6. hypercli_sdk-0.11.2/hypercli/personas.py +36 -0
  7. hypercli_sdk-0.11.2/hypercli/session_subscription.py +120 -0
  8. hypercli_sdk-0.11.2/hypercli/sessions.py +295 -0
  9. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/hypercli/user.py +10 -1
  10. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/pyproject.toml +1 -1
  11. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/tests/test_coding_agents.py +2 -6
  12. hypercli_sdk-0.11.2/tests/test_personas.py +91 -0
  13. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/tests/test_public_surface.py +8 -0
  14. hypercli_sdk-0.11.2/tests/test_rooms.py +265 -0
  15. hypercli_sdk-0.11.2/tests/test_sessions.py +460 -0
  16. hypercli_sdk-0.11.0/hypercli/sessions.py +0 -96
  17. hypercli_sdk-0.11.0/tests/test_sessions.py +0 -213
  18. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/.gitignore +0 -0
  19. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/hypercli/acp.py +0 -0
  20. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/hypercli/agent.py +0 -0
  21. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/hypercli/billing.py +0 -0
  22. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/hypercli/chat_integrations.py +0 -0
  23. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/hypercli/config.py +0 -0
  24. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/hypercli/files.py +0 -0
  25. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/hypercli/http.py +0 -0
  26. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/hypercli/instances.py +0 -0
  27. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/hypercli/job/__init__.py +0 -0
  28. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/hypercli/job/base.py +0 -0
  29. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/hypercli/job/comfyui.py +0 -0
  30. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/hypercli/job/gradio.py +0 -0
  31. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/hypercli/jobs.py +0 -0
  32. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/hypercli/keys.py +0 -0
  33. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/hypercli/logs.py +0 -0
  34. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/hypercli/mcp.py +0 -0
  35. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/hypercli/models.py +0 -0
  36. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/hypercli/renders.py +0 -0
  37. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/hypercli/routines.py +0 -0
  38. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/hypercli/runners.py +0 -0
  39. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/hypercli/shell.py +0 -0
  40. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/hypercli/voice.py +0 -0
  41. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/hypercli/voice_stream.py +0 -0
  42. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/hypercli/voice_transcription.py +0 -0
  43. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/hypercli/workspaces.py +0 -0
  44. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/hypercli/x402.py +0 -0
  45. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/tests/integration/conftest.py +0 -0
  46. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/tests/integration/test_agents.py +0 -0
  47. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/tests/integration/test_auth.py +0 -0
  48. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/tests/integration/test_billing.py +0 -0
  49. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/tests/integration/test_instances.py +0 -0
  50. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/tests/integration/test_jobs_dryrun.py +0 -0
  51. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/tests/integration/test_keys.py +0 -0
  52. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/tests/integration/test_renders.py +0 -0
  53. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/tests/test_acp.py +0 -0
  54. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/tests/test_agent_files_source.py +0 -0
  55. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/tests/test_agent_lifecycle.py +0 -0
  56. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/tests/test_agents.py +0 -0
  57. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/tests/test_apply_params.py +0 -0
  58. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/tests/test_bootstrap_agents_e2e_user.py +0 -0
  59. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/tests/test_bootstrap_console_test_key.py +0 -0
  60. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/tests/test_bootstrap_dev_test_keys.py +0 -0
  61. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/tests/test_chat_integrations.py +0 -0
  62. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/tests/test_claw.py +0 -0
  63. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/tests/test_config.py +0 -0
  64. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/tests/test_exec_shell_dryrun.py +0 -0
  65. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/tests/test_file_transport.py +0 -0
  66. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/tests/test_graph_to_api.py +0 -0
  67. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/tests/test_http.py +0 -0
  68. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/tests/test_jobs.py +0 -0
  69. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/tests/test_keys.py +0 -0
  70. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/tests/test_models.py +0 -0
  71. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/tests/test_parity_audit.py +0 -0
  72. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/tests/test_render_catalog.py +0 -0
  73. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/tests/test_renders_subscription.py +0 -0
  74. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/tests/test_repository_integrity.py +0 -0
  75. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/tests/test_routines.py +0 -0
  76. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/tests/test_runner_control_url.py +0 -0
  77. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/tests/test_runner_placement.py +0 -0
  78. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/tests/test_runners.py +0 -0
  79. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/tests/test_status.py +0 -0
  80. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/tests/test_voice.py +0 -0
  81. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/tests/test_voice_stream.py +0 -0
  82. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/tests/test_voice_transcription.py +0 -0
  83. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.2}/tests/test_workspaces.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: hypercli-sdk
3
- Version: 0.11.0
3
+ Version: 0.11.2
4
4
  Summary: Python SDK for HyperCLI - GPU orchestration and HyperAgent API
5
5
  Project-URL: Homepage, https://hypercli.com
6
6
  Project-URL: Documentation, https://docs.hypercli.com
@@ -377,6 +377,17 @@ agent.delete_secret("SERVICE_TOKEN")
377
377
  These methods return `AgentLaunchValueMutation` metadata. Secret writes never
378
378
  echo the secret value in their response.
379
379
 
380
+ ## Personas
381
+
382
+ `HyperCLI().personas` exposes the public `PersonasAPI`: `list()`,
383
+ `get(persona_id)`, and `resolve(agent_id=None)` read the live Backend catalog,
384
+ exact service-assembled artifact, and effective USER + SOUL respectively.
385
+ No persona artifacts are cached locally. See the [persona commands](../docs/cli/commands/persona.mdx).
386
+
387
+ The public `canonical_soul(meta)` helper reads stored canonical SOUL, not the
388
+ selected persona's effective SOUL. An explicit `meta.soul` (including an empty
389
+ or null value) takes precedence over legacy `meta.ui.soul`.
390
+
380
391
  ## Platform session metadata
381
392
 
382
393
  ```python
@@ -339,6 +339,17 @@ agent.delete_secret("SERVICE_TOKEN")
339
339
  These methods return `AgentLaunchValueMutation` metadata. Secret writes never
340
340
  echo the secret value in their response.
341
341
 
342
+ ## Personas
343
+
344
+ `HyperCLI().personas` exposes the public `PersonasAPI`: `list()`,
345
+ `get(persona_id)`, and `resolve(agent_id=None)` read the live Backend catalog,
346
+ exact service-assembled artifact, and effective USER + SOUL respectively.
347
+ No persona artifacts are cached locally. See the [persona commands](../docs/cli/commands/persona.mdx).
348
+
349
+ The public `canonical_soul(meta)` helper reads stored canonical SOUL, not the
350
+ selected persona's effective SOUL. An explicit `meta.soul` (including an empty
351
+ or null value) takes precedence over legacy `meta.ui.soul`.
352
+
342
353
  ## Platform session metadata
343
354
 
344
355
  ```python
@@ -53,11 +53,12 @@ from .workspaces import (
53
53
  WorkspacesAPI,
54
54
  )
55
55
  from .routines import Routine, RoutinesAPI
56
- from .sessions import SessionPage, SessionRecord, SessionSetup
56
+ from .sessions import RoomAgent, RoomMessage, RoomRecord, SessionPage, SessionRecord, SessionSetup, SessionMessage, SessionMessagePage, SessionMessageEvent
57
57
  from .runners import Runner, RunnerMeta, RunnerUiMeta, RunnersAPI
58
58
  from .x402 import X402Client, X402JobLaunch, X402FlowCreate, FlowCatalogItem
59
59
  from .files import File
60
60
  from .user import AuthMe, RuntimeIdentity, User, UserAPI
61
+ from .personas import PersonasAPI, canonical_soul
61
62
  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
62
63
  from .logs import LogStream, stream_logs, fetch_logs
63
64
  from .agents import (
@@ -158,14 +159,20 @@ from .acp import (
158
159
  AmbiguousDeliveryError,
159
160
  RetryableACPError,
160
161
  )
161
- __version__ = "0.11.0"
162
+ __version__ = "0.11.2"
162
163
  __all__ = [
163
164
  "CHAT_INTEGRATIONS",
164
165
  "build_chat_integration_config",
165
166
  "HyperCLI",
167
+ "RoomAgent",
168
+ "RoomMessage",
169
+ "RoomRecord",
166
170
  "SessionPage",
167
171
  "SessionRecord",
168
172
  "SessionSetup",
173
+ "SessionMessage",
174
+ "SessionMessagePage",
175
+ "SessionMessageEvent",
169
176
  "configure",
170
177
  "get_api_key",
171
178
  "get_agent_api_key",
@@ -238,6 +245,8 @@ __all__ = [
238
245
  "File",
239
246
  "User",
240
247
  "UserAPI",
248
+ "PersonasAPI",
249
+ "canonical_soul",
241
250
  "AuthMe",
242
251
  "RuntimeIdentity",
243
252
  "AsyncHTTPClient",
@@ -25,6 +25,7 @@ from typing import (
25
25
  Callable,
26
26
  Literal,
27
27
  Optional,
28
+ Sequence,
28
29
  Any,
29
30
  AsyncIterator,
30
31
  NotRequired,
@@ -45,7 +46,7 @@ from .config import (
45
46
  _default_agents_ws_url,
46
47
  )
47
48
  from .http import HTTPClient, APIError
48
- from .sessions import SessionPage, SessionRecord, SessionSetup
49
+ from .sessions import RoomMessage, RoomRecord, SessionPage, SessionRecord, SessionSetup, SessionMessagePage, SessionMessageEvent
49
50
 
50
51
 
51
52
  AGENTS_API_PREFIX = "/deployments"
@@ -262,17 +263,16 @@ DEFAULT_CODING_AGENT_IMAGES: dict[CodingAgentRuntime, str] = {
262
263
  DEFAULT_CODING_AGENT_SYNC_INCLUDES: dict[CodingAgentRuntime, tuple[str, ...] | None] = {
263
264
  "buzz-agent": None,
264
265
  "opencode": (
265
- ".hypercli/USER.md", ".hypercli/SOUL.md",
266
266
  ".config/opencode",
267
267
  ".local/share/opencode",
268
268
  ".local/state/opencode",
269
269
  ".cache/opencode",
270
270
  ),
271
- "codex": (".codex", ".hypercli/USER.md", ".hypercli/SOUL.md"),
272
- "claude-code": (".claude", ".claude.json", ".hypercli/USER.md", ".hypercli/SOUL.md"),
273
- "goose": (".goose", ".hypercli/USER.md", ".hypercli/SOUL.md"),
274
- "kimi-code": (".kimi-code", ".hypercli/USER.md", ".hypercli/SOUL.md"),
275
- "pi": (".pi", ".hypercli/USER.md", ".hypercli/SOUL.md"),
271
+ "codex": (".codex",),
272
+ "claude-code": (".claude", ".claude.json"),
273
+ "goose": (".goose",),
274
+ "kimi-code": (".kimi-code",),
275
+ "pi": (".pi",),
276
276
  }
277
277
  DEFAULT_BUZZ_CODING_AGENT_IMAGES: dict[CodingAgentRuntime, str] = {
278
278
  "buzz-agent": DEFAULT_BUZZ_AGENT_IMAGE,
@@ -1873,6 +1873,7 @@ class Agent:
1873
1873
  runtime: ManagedAgentRuntime | None = None,
1874
1874
  reset_image: bool | None = None,
1875
1875
  soul: str | None | object = _UNSET,
1876
+ persona: str | None | object = _UNSET,
1876
1877
  role: str | None | object = _UNSET,
1877
1878
  ui: dict | None = None,
1878
1879
  ) -> "Agent":
@@ -1885,6 +1886,7 @@ class Agent:
1885
1886
  runtime=runtime,
1886
1887
  reset_image=reset_image,
1887
1888
  soul=soul,
1889
+ persona=persona,
1888
1890
  role=role,
1889
1891
  ui=ui,
1890
1892
  )
@@ -3375,10 +3377,16 @@ class Deployments:
3375
3377
  runtime: ManagedAgentRuntime | None = None,
3376
3378
  reset_image: bool | None = None,
3377
3379
  soul: str | None | object = _UNSET,
3380
+ persona: str | None | object = _UNSET,
3378
3381
  role: str | None | object = _UNSET,
3379
3382
  ui: dict | None = None,
3380
3383
  ) -> Agent:
3384
+ """Update metadata. Backend requires agents:* owner access for soul/persona;
3385
+ runtime self-writes are denied. Omit to preserve; None clears.
3386
+ """
3381
3387
  body: dict[str, Any] = {}
3388
+ if persona is not _UNSET:
3389
+ body["persona"] = persona
3382
3390
  if soul is not _UNSET:
3383
3391
  body["soul"] = soul
3384
3392
  if role is not _UNSET:
@@ -3687,6 +3695,36 @@ class Deployments:
3687
3695
  raise ValueError("Session setup response does not match the requested session/agent")
3688
3696
  return result
3689
3697
 
3698
+ def get_session_messages(self, session_id: str, *, cursor: str | None = None, limit: int = 20) -> SessionMessagePage:
3699
+ """Canonical history, newest first. Feed next_cursor back unchanged for older rows.
3700
+
3701
+ The target limit may extend chunk/tool dependencies. This is not a
3702
+ transaction or gap-free boundary with a live subscription.
3703
+ """
3704
+ params: dict[str, Any] = {"limit": limit}
3705
+ if cursor is not None:
3706
+ params["cursor"] = cursor
3707
+ return SessionMessagePage.from_dict(self._get(
3708
+ f"/sessions/{quote(session_id, safe='')}/messages", params=params,
3709
+ ))
3710
+
3711
+ async def subscribe_session(
3712
+ self, session_id: str, handler: Callable[[SessionMessageEvent], Any], *,
3713
+ stop_event: asyncio.Event | None = None, on_ready: Callable[[], Any] | None = None,
3714
+ ) -> None:
3715
+ """Observe canonical messages until stopped/cancelled. Reconnects resubscribe.
3716
+
3717
+ on_ready runs after each subscribe ACK; no replay/gap-free guarantee.
3718
+ Protocol, subscription and callback failures propagate to the caller.
3719
+ """
3720
+ from .session_subscription import subscribe_session
3721
+ # Match the canonical UUID identity used in backend observer events.
3722
+ # Opaque references retain their existing server-validation behavior.
3723
+ if re.fullmatch(r"(?:[0-9a-f]{32}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})", session_id, re.IGNORECASE):
3724
+ session_id = str(UUID(session_id))
3725
+ await subscribe_session(self._agents_ws_url, self._api_key, session_id, handler,
3726
+ stop_event=stop_event, on_ready=on_ready)
3727
+
3690
3728
  def get_session(self, platform_session_id: str) -> SessionRecord:
3691
3729
  """Read stored metadata by platform session ID, never a runtime/leg ID.
3692
3730
 
@@ -3728,6 +3766,76 @@ class Deployments:
3728
3766
  params["cursor"] = cursor
3729
3767
  return SessionPage.from_dict(self._get("/sessions", params=params))
3730
3768
 
3769
+ def create_room(
3770
+ self,
3771
+ agents: Sequence[str],
3772
+ *,
3773
+ title: str | None = None,
3774
+ purpose: str = "",
3775
+ style: str = "",
3776
+ rules: Sequence[str] | None = None,
3777
+ token_limit: int | None = None,
3778
+ agent_turn_limit: int | None = None,
3779
+ ) -> RoomRecord:
3780
+ """Create an explicit multiparty room (docs/MULTIPARTY.md).
3781
+
3782
+ ``agents`` are agent UUID strings the authenticated owner is authorized
3783
+ to use; the backend validates the roster, brief, and both policy knobs.
3784
+ ``agent_turn_limit=None`` selects the product default (read back as the
3785
+ effective limit, 25 today, with the configured value null).
3786
+ """
3787
+ body = {
3788
+ "title": title,
3789
+ "purpose": purpose,
3790
+ "style": style,
3791
+ "rules": list(rules) if rules is not None else [],
3792
+ "agents": [str(agent) for agent in agents],
3793
+ "token_limit": token_limit,
3794
+ "agent_turn_limit": agent_turn_limit,
3795
+ }
3796
+ return RoomRecord.from_dict(self._post("/rooms", json=body))
3797
+
3798
+ def get_room(self, room_id: str) -> RoomRecord:
3799
+ """Read one room's brief, roster, policy, and status by room/session id."""
3800
+ return RoomRecord.from_dict(self._get(f"/rooms/{quote(room_id, safe='')}"))
3801
+
3802
+ def update_room(
3803
+ self, room_id: str, *, title: str | object = _UNSET, purpose: str | object = _UNSET,
3804
+ style: str | object = _UNSET, rules: Sequence[str] | object = _UNSET,
3805
+ token_limit: int | object = _UNSET, agent_turn_limit: int | object = _UNSET,
3806
+ status: str | object = _UNSET,
3807
+ ) -> RoomRecord:
3808
+ """Owner-edit a room brief, policy knobs, or status.
3809
+
3810
+ Omitted fields are preserved. Supplied ``None`` clears brief text,
3811
+ and restores a policy knob's product default; ``status`` accepts
3812
+ ``live`` or ``archived``. Policy changes take effect at the next
3813
+ authenticated-human-message epoch.
3814
+ """
3815
+ supplied = {
3816
+ "title": title, "purpose": purpose, "style": style, "rules": rules,
3817
+ "token_limit": token_limit, "agent_turn_limit": agent_turn_limit, "status": status,
3818
+ }
3819
+ body = {key: (list(value) if key == "rules" else value)
3820
+ for key, value in supplied.items() if value is not _UNSET}
3821
+ return RoomRecord.from_dict(self._patch(f"/rooms/{quote(room_id, safe='')}", json=body))
3822
+
3823
+ def create_room_message(
3824
+ self, room_id: str, body: str, *, reply_to: str | None = None,
3825
+ ) -> RoomMessage:
3826
+ """Commit one authenticated human message; fanout stays backend-owned.
3827
+
3828
+ The response carries the canonical message identity, its epoch, and
3829
+ the backend's per-agent delivery map. Automatic agent turns are not
3830
+ awaited or relayed here.
3831
+ """
3832
+ payload: dict[str, Any] = {"body": body}
3833
+ if reply_to is not None:
3834
+ payload["reply_to"] = reply_to
3835
+ return RoomMessage.from_dict(
3836
+ self._post(f"/rooms/{quote(room_id, safe='')}/messages", json=payload)
3837
+ )
3838
+
3731
3839
  def redeem_grant_code(self, code: str, *, extend_existing: bool | None = None) -> dict:
3732
3840
  """Redeem a promo/activation grant code via POST /billing/grants/redeem.
3733
3841
 
@@ -11,6 +11,7 @@ from .http import HTTPClient
11
11
  from .billing import Billing
12
12
  from .jobs import Jobs
13
13
  from .user import UserAPI
14
+ from .personas import PersonasAPI
14
15
  from .instances import Instances
15
16
  from .renders import Renders
16
17
  from .files import Files
@@ -94,7 +95,8 @@ class HyperCLI:
94
95
  )
95
96
  self.billing = Billing(self._http)
96
97
  self.jobs = Jobs(self._http)
97
- self.user = UserAPI(self._http)
98
+ self.user = UserAPI(self._http, profile_http=self._agents_http)
99
+ self.personas = PersonasAPI(self._agents_http)
98
100
  self.instances = Instances(self._http)
99
101
  self.renders = Renders(self._http)
100
102
  self.files = Files(self._http)
@@ -0,0 +1,36 @@
1
+ """Live Backend persona discovery and resolution. No artifacts or disk cache."""
2
+ import re
3
+ from typing import TYPE_CHECKING
4
+
5
+ if TYPE_CHECKING:
6
+ from .http import HTTPClient
7
+
8
+
9
+ def canonical_soul(meta: dict | None) -> str:
10
+ """Read stored canonical SOUL, never the effective selected persona."""
11
+ meta = meta or {}
12
+ value = meta.get("soul") if "soul" in meta else (meta.get("ui") or {}).get("soul")
13
+ return value if isinstance(value, str) else ""
14
+
15
+
16
+ class PersonasAPI:
17
+ def __init__(self, http: "HTTPClient"):
18
+ self._http = http
19
+
20
+ def list(self) -> dict:
21
+ """Read the current authorized catalog."""
22
+ return self._http.get("/personas")
23
+
24
+ def get(self, persona_id: str) -> dict:
25
+ """Read exact service-assembled INDEX.md; never concatenate locally."""
26
+ if len(persona_id) > 64 or not re.fullmatch(r"[a-z0-9]+(?:-[a-z0-9]+)*", persona_id):
27
+ raise ValueError("persona id must be an exact lowercase hyphenated identifier")
28
+ return self._http.get(f"/personas/{persona_id}")
29
+
30
+ def resolve(self, agent_id: str | None = None) -> dict:
31
+ """Resolve current USER + effective SOUL. Backend owns authorization,
32
+ bound-Agent inference and canonical precedence; failures never fall back.
33
+ """
34
+ if agent_id is not None and not agent_id.strip():
35
+ raise ValueError("agent_id must not be blank")
36
+ return self._http.get("/personas/resolve", params=None if agent_id is None else {"agent_id": agent_id})
@@ -0,0 +1,120 @@
1
+ """Read-only product /ws observer, independent of native ACP connections."""
2
+
3
+ import asyncio
4
+ import inspect
5
+ import json
6
+ from collections.abc import Callable
7
+ from contextlib import suppress
8
+ from typing import Any
9
+ from urllib.parse import parse_qsl, urlencode, urlsplit, urlunsplit
10
+
11
+ import websockets
12
+ from websockets.exceptions import ConnectionClosed, InvalidStatus
13
+
14
+ from .sessions import SessionMessage, SessionMessageEvent
15
+
16
+
17
+ class _CallbackError(Exception):
18
+ """Keep user callback failures outside transport retry classification."""
19
+
20
+ def __init__(self, error: Exception):
21
+ self.error = error
22
+
23
+
24
+ async def subscribe_session(
25
+ ws_url: str, credential: str, session_id: str,
26
+ handler: Callable[[SessionMessageEvent], Any], *,
27
+ stop_event: asyncio.Event | None = None, on_ready: Callable[[], Any] | None = None,
28
+ ) -> None:
29
+ if not session_id:
30
+ raise ValueError("session_id is required")
31
+ parts = urlsplit(ws_url)
32
+ query = dict(parse_qsl(parts.query))
33
+ query.update(mode="observe", token=credential)
34
+ url = urlunsplit(parts._replace(query=urlencode(query)))
35
+
36
+ async def callback(fn, *args):
37
+ if fn is not None:
38
+ try:
39
+ result = fn(*args)
40
+ if inspect.isawaitable(result):
41
+ await result
42
+ except Exception as exc:
43
+ raise _CallbackError(exc) from exc
44
+
45
+ async def run():
46
+ delay = 0.25
47
+ request = 0
48
+ while stop_event is None or not stop_event.is_set():
49
+ started = asyncio.get_running_loop().time()
50
+ connected = False
51
+ try:
52
+ async with websockets.connect(url, ping_interval=20, ping_timeout=20) as ws:
53
+ connected = True
54
+ ready = json.loads(await asyncio.wait_for(ws.recv(), 10))
55
+ if not isinstance(ready, dict) or ready.get("type") != "ready":
56
+ raise ValueError("Session observer did not send ready")
57
+ request += 1
58
+ request_id = str(request)
59
+ await ws.send(json.dumps({"type": "sessionSubscribe", "requestId": request_id, "sessionId": session_id}))
60
+ ack = json.loads(await asyncio.wait_for(ws.recv(), 10))
61
+ if (not isinstance(ack, dict) or ack.get("requestId") != request_id
62
+ or ack.get("sessionId") != session_id):
63
+ raise ValueError("Invalid session subscription acknowledgement")
64
+ if ack.get("type") == "sessionSubscriptionError":
65
+ raise ValueError(ack.get("message") or "Session subscription rejected")
66
+ if ack.get("type") != "sessionSubscribed":
67
+ raise ValueError("Invalid session subscription acknowledgement")
68
+ try:
69
+ await callback(on_ready)
70
+ while stop_event is None or not stop_event.is_set():
71
+ frame = json.loads(await ws.recv())
72
+ if (not isinstance(frame, dict) or frame.get("sessionId") != session_id):
73
+ raise ValueError("Invalid session observer event")
74
+ if frame.get("type") == "sessionSubscriptionError":
75
+ raise ValueError(frame.get("message") or "Session subscription rejected")
76
+ if frame.get("type") != "sessionMessage":
77
+ raise ValueError("Invalid session observer event")
78
+ message = SessionMessage.from_dict(frame.get("message"))
79
+ if message.session_id != session_id:
80
+ raise ValueError("Session message does not match selected session")
81
+ await callback(handler, SessionMessageEvent("sessionMessage", session_id, message))
82
+ finally:
83
+ if ws.state.name == "OPEN":
84
+ with suppress(ConnectionClosed):
85
+ await ws.send(json.dumps({"type": "sessionUnsubscribe", "requestId": str(request + 1), "sessionId": session_id}))
86
+ except _CallbackError as exc:
87
+ raise exc.error
88
+ except ConnectionClosed as exc:
89
+ if exc.rcvd and exc.rcvd.code in {1008, 4401, 4403}:
90
+ raise
91
+ except InvalidStatus as exc:
92
+ if exc.response.status_code in {401, 403}:
93
+ raise
94
+ except TimeoutError:
95
+ # Opening the transport can be retried. Once open, a missing
96
+ # ready/subscribed frame is a terminal protocol timeout.
97
+ if connected:
98
+ raise
99
+ except OSError:
100
+ pass
101
+ if asyncio.get_running_loop().time() - started >= 10:
102
+ delay = 0.25
103
+ await asyncio.sleep(delay)
104
+ delay = min(delay * 2, 5)
105
+
106
+ if stop_event is None:
107
+ await run()
108
+ return
109
+ if stop_event.is_set():
110
+ return
111
+ task = asyncio.create_task(run())
112
+ stopped = asyncio.create_task(stop_event.wait())
113
+ try:
114
+ done, _ = await asyncio.wait((task, stopped), return_when=asyncio.FIRST_COMPLETED)
115
+ if task in done:
116
+ await task
117
+ finally:
118
+ task.cancel()
119
+ stopped.cancel()
120
+ await asyncio.gather(task, stopped, return_exceptions=True)