hypercli-sdk 0.11.1__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 (82) hide show
  1. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/PKG-INFO +12 -1
  2. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/README.md +11 -0
  3. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/hypercli/__init__.py +8 -2
  4. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/hypercli/agents.py +44 -7
  5. {hypercli_sdk-0.11.1 → 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.1 → hypercli_sdk-0.11.2}/hypercli/sessions.py +56 -0
  9. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/hypercli/user.py +10 -1
  10. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/pyproject.toml +1 -1
  11. {hypercli_sdk-0.11.1 → 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.1 → hypercli_sdk-0.11.2}/tests/test_public_surface.py +5 -0
  14. hypercli_sdk-0.11.2/tests/test_sessions.py +460 -0
  15. hypercli_sdk-0.11.1/tests/test_sessions.py +0 -213
  16. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/.gitignore +0 -0
  17. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/hypercli/acp.py +0 -0
  18. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/hypercli/agent.py +0 -0
  19. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/hypercli/billing.py +0 -0
  20. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/hypercli/chat_integrations.py +0 -0
  21. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/hypercli/config.py +0 -0
  22. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/hypercli/files.py +0 -0
  23. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/hypercli/http.py +0 -0
  24. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/hypercli/instances.py +0 -0
  25. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/hypercli/job/__init__.py +0 -0
  26. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/hypercli/job/base.py +0 -0
  27. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/hypercli/job/comfyui.py +0 -0
  28. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/hypercli/job/gradio.py +0 -0
  29. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/hypercli/jobs.py +0 -0
  30. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/hypercli/keys.py +0 -0
  31. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/hypercli/logs.py +0 -0
  32. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/hypercli/mcp.py +0 -0
  33. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/hypercli/models.py +0 -0
  34. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/hypercli/renders.py +0 -0
  35. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/hypercli/routines.py +0 -0
  36. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/hypercli/runners.py +0 -0
  37. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/hypercli/shell.py +0 -0
  38. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/hypercli/voice.py +0 -0
  39. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/hypercli/voice_stream.py +0 -0
  40. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/hypercli/voice_transcription.py +0 -0
  41. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/hypercli/workspaces.py +0 -0
  42. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/hypercli/x402.py +0 -0
  43. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/integration/conftest.py +0 -0
  44. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/integration/test_agents.py +0 -0
  45. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/integration/test_auth.py +0 -0
  46. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/integration/test_billing.py +0 -0
  47. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/integration/test_instances.py +0 -0
  48. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/integration/test_jobs_dryrun.py +0 -0
  49. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/integration/test_keys.py +0 -0
  50. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/integration/test_renders.py +0 -0
  51. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/test_acp.py +0 -0
  52. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/test_agent_files_source.py +0 -0
  53. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/test_agent_lifecycle.py +0 -0
  54. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/test_agents.py +0 -0
  55. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/test_apply_params.py +0 -0
  56. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/test_bootstrap_agents_e2e_user.py +0 -0
  57. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/test_bootstrap_console_test_key.py +0 -0
  58. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/test_bootstrap_dev_test_keys.py +0 -0
  59. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/test_chat_integrations.py +0 -0
  60. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/test_claw.py +0 -0
  61. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/test_config.py +0 -0
  62. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/test_exec_shell_dryrun.py +0 -0
  63. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/test_file_transport.py +0 -0
  64. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/test_graph_to_api.py +0 -0
  65. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/test_http.py +0 -0
  66. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/test_jobs.py +0 -0
  67. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/test_keys.py +0 -0
  68. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/test_models.py +0 -0
  69. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/test_parity_audit.py +0 -0
  70. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/test_render_catalog.py +0 -0
  71. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/test_renders_subscription.py +0 -0
  72. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/test_repository_integrity.py +0 -0
  73. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/test_rooms.py +0 -0
  74. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/test_routines.py +0 -0
  75. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/test_runner_control_url.py +0 -0
  76. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/test_runner_placement.py +0 -0
  77. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/test_runners.py +0 -0
  78. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/test_status.py +0 -0
  79. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/test_voice.py +0 -0
  80. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/test_voice_stream.py +0 -0
  81. {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/test_voice_transcription.py +0 -0
  82. {hypercli_sdk-0.11.1 → 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.1
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 RoomAgent, RoomMessage, RoomRecord, 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,7 +159,7 @@ from .acp import (
158
159
  AmbiguousDeliveryError,
159
160
  RetryableACPError,
160
161
  )
161
- __version__ = "0.11.1"
162
+ __version__ = "0.11.2"
162
163
  __all__ = [
163
164
  "CHAT_INTEGRATIONS",
164
165
  "build_chat_integration_config",
@@ -169,6 +170,9 @@ __all__ = [
169
170
  "SessionPage",
170
171
  "SessionRecord",
171
172
  "SessionSetup",
173
+ "SessionMessage",
174
+ "SessionMessagePage",
175
+ "SessionMessageEvent",
172
176
  "configure",
173
177
  "get_api_key",
174
178
  "get_agent_api_key",
@@ -241,6 +245,8 @@ __all__ = [
241
245
  "File",
242
246
  "User",
243
247
  "UserAPI",
248
+ "PersonasAPI",
249
+ "canonical_soul",
244
250
  "AuthMe",
245
251
  "RuntimeIdentity",
246
252
  "AsyncHTTPClient",
@@ -46,7 +46,7 @@ from .config import (
46
46
  _default_agents_ws_url,
47
47
  )
48
48
  from .http import HTTPClient, APIError
49
- from .sessions import RoomMessage, RoomRecord, SessionPage, SessionRecord, SessionSetup
49
+ from .sessions import RoomMessage, RoomRecord, SessionPage, SessionRecord, SessionSetup, SessionMessagePage, SessionMessageEvent
50
50
 
51
51
 
52
52
  AGENTS_API_PREFIX = "/deployments"
@@ -263,17 +263,16 @@ DEFAULT_CODING_AGENT_IMAGES: dict[CodingAgentRuntime, str] = {
263
263
  DEFAULT_CODING_AGENT_SYNC_INCLUDES: dict[CodingAgentRuntime, tuple[str, ...] | None] = {
264
264
  "buzz-agent": None,
265
265
  "opencode": (
266
- ".hypercli/USER.md", ".hypercli/SOUL.md",
267
266
  ".config/opencode",
268
267
  ".local/share/opencode",
269
268
  ".local/state/opencode",
270
269
  ".cache/opencode",
271
270
  ),
272
- "codex": (".codex", ".hypercli/USER.md", ".hypercli/SOUL.md"),
273
- "claude-code": (".claude", ".claude.json", ".hypercli/USER.md", ".hypercli/SOUL.md"),
274
- "goose": (".goose", ".hypercli/USER.md", ".hypercli/SOUL.md"),
275
- "kimi-code": (".kimi-code", ".hypercli/USER.md", ".hypercli/SOUL.md"),
276
- "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",),
277
276
  }
278
277
  DEFAULT_BUZZ_CODING_AGENT_IMAGES: dict[CodingAgentRuntime, str] = {
279
278
  "buzz-agent": DEFAULT_BUZZ_AGENT_IMAGE,
@@ -1874,6 +1873,7 @@ class Agent:
1874
1873
  runtime: ManagedAgentRuntime | None = None,
1875
1874
  reset_image: bool | None = None,
1876
1875
  soul: str | None | object = _UNSET,
1876
+ persona: str | None | object = _UNSET,
1877
1877
  role: str | None | object = _UNSET,
1878
1878
  ui: dict | None = None,
1879
1879
  ) -> "Agent":
@@ -1886,6 +1886,7 @@ class Agent:
1886
1886
  runtime=runtime,
1887
1887
  reset_image=reset_image,
1888
1888
  soul=soul,
1889
+ persona=persona,
1889
1890
  role=role,
1890
1891
  ui=ui,
1891
1892
  )
@@ -3376,10 +3377,16 @@ class Deployments:
3376
3377
  runtime: ManagedAgentRuntime | None = None,
3377
3378
  reset_image: bool | None = None,
3378
3379
  soul: str | None | object = _UNSET,
3380
+ persona: str | None | object = _UNSET,
3379
3381
  role: str | None | object = _UNSET,
3380
3382
  ui: dict | None = None,
3381
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
+ """
3382
3387
  body: dict[str, Any] = {}
3388
+ if persona is not _UNSET:
3389
+ body["persona"] = persona
3383
3390
  if soul is not _UNSET:
3384
3391
  body["soul"] = soul
3385
3392
  if role is not _UNSET:
@@ -3688,6 +3695,36 @@ class Deployments:
3688
3695
  raise ValueError("Session setup response does not match the requested session/agent")
3689
3696
  return result
3690
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
+
3691
3728
  def get_session(self, platform_session_id: str) -> SessionRecord:
3692
3729
  """Read stored metadata by platform session ID, never a runtime/leg ID.
3693
3730
 
@@ -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)
@@ -7,6 +7,62 @@ from typing import Any
7
7
  from acp import schema
8
8
 
9
9
 
10
+ @dataclass
11
+ class SessionMessage:
12
+ """Canonical persisted message DTO; ACP payloads are retained at full fidelity."""
13
+
14
+ session_id: str
15
+ seq: int
16
+ role: str
17
+ acp: dict[str, Any]
18
+ message_id: str | None = None
19
+ meta: dict[str, Any] | None = None
20
+ stop_reason: str | None = None
21
+ created_at: str | None = None
22
+ delivered_at: str | None = None
23
+ completed_at: str | None = None
24
+ participant_kind: str | None = None
25
+ participant_id: str | None = None
26
+
27
+ @classmethod
28
+ def from_dict(cls, data: dict[str, Any]) -> "SessionMessage":
29
+ if (not isinstance(data, dict) or not isinstance(data.get("session_id"), str)
30
+ or not data["session_id"]
31
+ or type(data.get("seq")) is not int or data["seq"] < 1
32
+ or data.get("role") not in ("user", "assistant", "tool")
33
+ or not (data.get("message_id") is None or isinstance(data["message_id"], str))
34
+ or not isinstance(data.get("acp"), dict)):
35
+ raise ValueError("Invalid session message")
36
+ return cls(**{key: deepcopy(data[key]) for key in cls.__dataclass_fields__ if key in data})
37
+
38
+
39
+ @dataclass
40
+ class SessionMessagePage:
41
+ items: list[SessionMessage]
42
+ next_cursor: str | None = None
43
+ has_more: bool = False
44
+ head_seq: int | None = None
45
+ import_outcome: dict[str, Any] | None = None
46
+
47
+ @classmethod
48
+ def from_dict(cls, data: dict[str, Any]) -> "SessionMessagePage":
49
+ if (not isinstance(data, dict) or not isinstance(data.get("items"), list)
50
+ or type(data.get("has_more")) is not bool
51
+ or not (data.get("next_cursor") is None or isinstance(data["next_cursor"], str))
52
+ or (data["has_more"] and not data.get("next_cursor"))):
53
+ raise ValueError("Invalid session message page")
54
+ return cls(items=[SessionMessage.from_dict(row) for row in data["items"]],
55
+ next_cursor=data.get("next_cursor"), has_more=data["has_more"],
56
+ head_seq=data.get("head_seq"), import_outcome=deepcopy(data.get("import_outcome")))
57
+
58
+
59
+ @dataclass
60
+ class SessionMessageEvent:
61
+ type: str
62
+ session_id: str
63
+ message: SessionMessage
64
+
65
+
10
66
  def _parse_session_setup(setup: Any) -> dict[str, Any]:
11
67
  if not isinstance(setup, dict) or not isinstance(setup.get("mcpServers"), list):
12
68
  raise ValueError("Invalid session setup: expected an object with mcpServers")
@@ -141,9 +141,18 @@ def _derive_external_id(
141
141
  class UserAPI:
142
142
  """User API wrapper"""
143
143
 
144
- def __init__(self, http: "HTTPClient", auth_http: Optional["HTTPClient"] = None):
144
+ def __init__(self, http: "HTTPClient", auth_http: Optional["HTTPClient"] = None, profile_http: Optional["HTTPClient"] = None):
145
145
  self._http = http
146
146
  self._auth_http = auth_http or http
147
+ self._profile_http = profile_http or http
148
+
149
+ def get_profile(self) -> dict:
150
+ """Read canonical USER Markdown from the Backend; no local projection."""
151
+ return self._profile_http.get("/users/profile")
152
+
153
+ def update_profile(self, profile: str | None) -> dict:
154
+ """Write canonical USER. Backend requires user-family write access; None clears."""
155
+ return self._profile_http.patch("/users/profile", json={"profile": profile})
147
156
 
148
157
  def get(self) -> User:
149
158
  """Get current user info"""
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "hypercli-sdk"
7
- version = "0.11.1"
7
+ version = "0.11.2"
8
8
  description = "Python SDK for HyperCLI - GPU orchestration and HyperAgent API"
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.10"
@@ -421,10 +421,8 @@ class TestCreateAgentCodingRuntimes:
421
421
 
422
422
  body = posts[0][1]
423
423
  assert "sync_exclude" not in body
424
- assert body["sync_include"][-2:] == [".hypercli/USER.md", ".hypercli/SOUL.md"] or runtime in (
425
- "opencode",
426
- "pi",
427
- )
424
+ assert ".hypercli/USER.md" not in body["sync_include"]
425
+ assert ".hypercli/SOUL.md" not in body["sync_include"]
428
426
 
429
427
  def test_buzz_runtime_defaults_to_whole_root_with_empty_exclude(self, monkeypatch):
430
428
  deployments, posts = _capture_create(monkeypatch, "buzz-agent")
@@ -441,8 +439,6 @@ class TestCreateAgentCodingRuntimes:
441
439
  deployments.create_agent("opencode")
442
440
 
443
441
  assert posts[0][1]["sync_include"] == [
444
- ".hypercli/USER.md",
445
- ".hypercli/SOUL.md",
446
442
  ".config/opencode",
447
443
  ".local/share/opencode",
448
444
  ".local/state/opencode",
@@ -0,0 +1,91 @@
1
+ from unittest.mock import Mock
2
+
3
+ import httpx
4
+ import pytest
5
+
6
+ from hypercli import HyperCLI
7
+ from hypercli.agents import Deployments
8
+ from hypercli.personas import PersonasAPI, canonical_soul
9
+ from hypercli.user import UserAPI
10
+
11
+
12
+ @pytest.mark.parametrize(("method", "args", "path", "params", "payload"), [
13
+ ("list", (), "/agents/personas", {}, {"personas": []}),
14
+ ("get", ("researcher",), "/agents/personas/researcher", {}, {"id": "researcher"}),
15
+ ("resolve", (), "/agents/personas/resolve", {}, {"soul": "bound"}),
16
+ ("resolve", ("agent-id",), "/agents/personas/resolve",
17
+ {"agent_id": "agent-id"}, {"soul": "explicit"}),
18
+ ])
19
+ def test_client_personas_use_authenticated_backend_http(monkeypatch, method, args, path, params, payload):
20
+ """Retain the API contract independently of the retired Python CLI."""
21
+ requests = []
22
+
23
+ def send(_client, request, **kwargs):
24
+ requests.append(request)
25
+ return httpx.Response(200, json=payload, request=request)
26
+
27
+ monkeypatch.setattr(httpx.Client, "send", send)
28
+ client = HyperCLI(api_key="test", agents_api_base_url="https://backend.invalid/agents")
29
+ assert getattr(client.personas, method)(*args) == payload
30
+ assert len(requests) == 1
31
+ request = requests[0]
32
+ assert request.method == "GET"
33
+ assert request.url.host == "backend.invalid"
34
+ assert request.url.path == path
35
+ assert dict(request.url.params) == params
36
+ assert request.headers["Authorization"] == "Bearer test"
37
+
38
+
39
+ def test_live_reads_no_cache_and_no_failure_fallback():
40
+ http = Mock()
41
+ api = PersonasAPI(http)
42
+ http.get.side_effect = [{"soul": "first"}, {"soul": "second"}, RuntimeError("unavailable")]
43
+ assert api.resolve("agent")["soul"] == "first"
44
+ assert api.resolve("agent")["soul"] == "second"
45
+ with pytest.raises(RuntimeError, match="unavailable"):
46
+ api.resolve("agent")
47
+ http.get.assert_called_with("/personas/resolve", params={"agent_id": "agent"})
48
+
49
+
50
+ def test_catalog_and_exact_artifact_paths():
51
+ http = Mock()
52
+ api = PersonasAPI(http)
53
+ api.list()
54
+ http.get.assert_called_with("/personas")
55
+ api.get("researcher")
56
+ http.get.assert_called_with("/personas/researcher")
57
+ for value in ["", "../x", "UPPER", "a" * 65]:
58
+ with pytest.raises(ValueError):
59
+ api.get(value)
60
+ with pytest.raises(ValueError):
61
+ api.resolve(" ")
62
+
63
+
64
+ def test_canonical_soul_does_not_resolve_persona_or_override_clear():
65
+ assert canonical_soul({"soul": "stored", "persona": "researcher"}) == "stored"
66
+ for value in [None, ""]:
67
+ assert canonical_soul({"soul": value, "ui": {"soul": "legacy"}}) == ""
68
+ assert canonical_soul({"ui": {"soul": "legacy"}}) == "legacy"
69
+
70
+
71
+ def test_profile_uses_agents_endpoint_not_product_or_files():
72
+ product, backend = Mock(), Mock()
73
+ api = UserAPI(product, profile_http=backend)
74
+ api.get_profile()
75
+ backend.get.assert_called_once_with("/users/profile")
76
+ api.update_profile(None)
77
+ backend.patch.assert_called_once_with("/users/profile", json={"profile": None})
78
+ assert not product.mock_calls
79
+
80
+
81
+ def test_selector_update_preserves_omission_and_explicit_clear(monkeypatch):
82
+ api = Deployments(Mock(), api_key="test", api_base="https://example.test/agents")
83
+ patch = Mock(return_value={"id": "agent", "meta": {"soul": "stored"}})
84
+ monkeypatch.setattr(api, "_patch", patch)
85
+ monkeypatch.setattr(api, "resolve_agent_id", lambda value: value)
86
+ for value in ["researcher", None]:
87
+ agent = api.update("agent", persona=value)
88
+ patch.assert_called_with("/deployments/agent", json={"persona": value})
89
+ assert canonical_soul(agent.meta) == "stored"
90
+ api.update("agent", soul="new")
91
+ patch.assert_called_with("/deployments/agent", json={"soul": "new"})
@@ -124,6 +124,7 @@ EXPECTED_PUBLIC_SURFACE = frozenset(
124
124
  "Model",
125
125
  "ModelsAPI",
126
126
  "OPENCLAW_TRUSTED_PROXIES_ENV",
127
+ "PersonasAPI",
127
128
  "PricingTier",
128
129
  "Region",
129
130
  "Render",
@@ -143,6 +144,9 @@ EXPECTED_PUBLIC_SURFACE = frozenset(
143
144
  "RoomAgent",
144
145
  "RoomMessage",
145
146
  "RoomRecord",
147
+ "SessionMessage",
148
+ "SessionMessageEvent",
149
+ "SessionMessagePage",
146
150
  "SessionPage",
147
151
  "SessionRecord",
148
152
  "SessionSetup",
@@ -175,6 +179,7 @@ EXPECTED_PUBLIC_SURFACE = frozenset(
175
179
  "build_openclaw_trusted_proxies_env",
176
180
  "build_openclaw_workspaces_sync_env",
177
181
  "configure",
182
+ "canonical_soul",
178
183
  "expand_subgraphs",
179
184
  "fetch_logs",
180
185
  "find_by_hostname",