hypercli-sdk 0.11.0__tar.gz → 0.11.1__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 (79) hide show
  1. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/PKG-INFO +1 -1
  2. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/hypercli/__init__.py +5 -2
  3. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/hypercli/agents.py +72 -1
  4. hypercli_sdk-0.11.1/hypercli/sessions.py +239 -0
  5. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/pyproject.toml +1 -1
  6. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/tests/test_public_surface.py +3 -0
  7. hypercli_sdk-0.11.1/tests/test_rooms.py +265 -0
  8. hypercli_sdk-0.11.0/hypercli/sessions.py +0 -96
  9. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/.gitignore +0 -0
  10. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/README.md +0 -0
  11. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/hypercli/acp.py +0 -0
  12. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/hypercli/agent.py +0 -0
  13. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/hypercli/billing.py +0 -0
  14. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/hypercli/chat_integrations.py +0 -0
  15. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/hypercli/client.py +0 -0
  16. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/hypercli/config.py +0 -0
  17. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/hypercli/files.py +0 -0
  18. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/hypercli/http.py +0 -0
  19. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/hypercli/instances.py +0 -0
  20. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/hypercli/job/__init__.py +0 -0
  21. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/hypercli/job/base.py +0 -0
  22. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/hypercli/job/comfyui.py +0 -0
  23. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/hypercli/job/gradio.py +0 -0
  24. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/hypercli/jobs.py +0 -0
  25. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/hypercli/keys.py +0 -0
  26. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/hypercli/logs.py +0 -0
  27. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/hypercli/mcp.py +0 -0
  28. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/hypercli/models.py +0 -0
  29. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/hypercli/renders.py +0 -0
  30. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/hypercli/routines.py +0 -0
  31. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/hypercli/runners.py +0 -0
  32. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/hypercli/shell.py +0 -0
  33. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/hypercli/user.py +0 -0
  34. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/hypercli/voice.py +0 -0
  35. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/hypercli/voice_stream.py +0 -0
  36. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/hypercli/voice_transcription.py +0 -0
  37. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/hypercli/workspaces.py +0 -0
  38. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/hypercli/x402.py +0 -0
  39. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/tests/integration/conftest.py +0 -0
  40. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/tests/integration/test_agents.py +0 -0
  41. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/tests/integration/test_auth.py +0 -0
  42. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/tests/integration/test_billing.py +0 -0
  43. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/tests/integration/test_instances.py +0 -0
  44. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/tests/integration/test_jobs_dryrun.py +0 -0
  45. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/tests/integration/test_keys.py +0 -0
  46. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/tests/integration/test_renders.py +0 -0
  47. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/tests/test_acp.py +0 -0
  48. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/tests/test_agent_files_source.py +0 -0
  49. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/tests/test_agent_lifecycle.py +0 -0
  50. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/tests/test_agents.py +0 -0
  51. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/tests/test_apply_params.py +0 -0
  52. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/tests/test_bootstrap_agents_e2e_user.py +0 -0
  53. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/tests/test_bootstrap_console_test_key.py +0 -0
  54. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/tests/test_bootstrap_dev_test_keys.py +0 -0
  55. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/tests/test_chat_integrations.py +0 -0
  56. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/tests/test_claw.py +0 -0
  57. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/tests/test_coding_agents.py +0 -0
  58. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/tests/test_config.py +0 -0
  59. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/tests/test_exec_shell_dryrun.py +0 -0
  60. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/tests/test_file_transport.py +0 -0
  61. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/tests/test_graph_to_api.py +0 -0
  62. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/tests/test_http.py +0 -0
  63. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/tests/test_jobs.py +0 -0
  64. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/tests/test_keys.py +0 -0
  65. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/tests/test_models.py +0 -0
  66. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/tests/test_parity_audit.py +0 -0
  67. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/tests/test_render_catalog.py +0 -0
  68. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/tests/test_renders_subscription.py +0 -0
  69. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/tests/test_repository_integrity.py +0 -0
  70. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/tests/test_routines.py +0 -0
  71. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/tests/test_runner_control_url.py +0 -0
  72. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/tests/test_runner_placement.py +0 -0
  73. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/tests/test_runners.py +0 -0
  74. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/tests/test_sessions.py +0 -0
  75. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/tests/test_status.py +0 -0
  76. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/tests/test_voice.py +0 -0
  77. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/tests/test_voice_stream.py +0 -0
  78. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/tests/test_voice_transcription.py +0 -0
  79. {hypercli_sdk-0.11.0 → hypercli_sdk-0.11.1}/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.1
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
@@ -53,7 +53,7 @@ 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
57
57
  from .runners import Runner, RunnerMeta, RunnerUiMeta, RunnersAPI
58
58
  from .x402 import X402Client, X402JobLaunch, X402FlowCreate, FlowCatalogItem
59
59
  from .files import File
@@ -158,11 +158,14 @@ from .acp import (
158
158
  AmbiguousDeliveryError,
159
159
  RetryableACPError,
160
160
  )
161
- __version__ = "0.11.0"
161
+ __version__ = "0.11.1"
162
162
  __all__ = [
163
163
  "CHAT_INTEGRATIONS",
164
164
  "build_chat_integration_config",
165
165
  "HyperCLI",
166
+ "RoomAgent",
167
+ "RoomMessage",
168
+ "RoomRecord",
166
169
  "SessionPage",
167
170
  "SessionRecord",
168
171
  "SessionSetup",
@@ -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
49
50
 
50
51
 
51
52
  AGENTS_API_PREFIX = "/deployments"
@@ -3728,6 +3729,76 @@ class Deployments:
3728
3729
  params["cursor"] = cursor
3729
3730
  return SessionPage.from_dict(self._get("/sessions", params=params))
3730
3731
 
3732
+ def create_room(
3733
+ self,
3734
+ agents: Sequence[str],
3735
+ *,
3736
+ title: str | None = None,
3737
+ purpose: str = "",
3738
+ style: str = "",
3739
+ rules: Sequence[str] | None = None,
3740
+ token_limit: int | None = None,
3741
+ agent_turn_limit: int | None = None,
3742
+ ) -> RoomRecord:
3743
+ """Create an explicit multiparty room (docs/MULTIPARTY.md).
3744
+
3745
+ ``agents`` are agent UUID strings the authenticated owner is authorized
3746
+ to use; the backend validates the roster, brief, and both policy knobs.
3747
+ ``agent_turn_limit=None`` selects the product default (read back as the
3748
+ effective limit, 25 today, with the configured value null).
3749
+ """
3750
+ body = {
3751
+ "title": title,
3752
+ "purpose": purpose,
3753
+ "style": style,
3754
+ "rules": list(rules) if rules is not None else [],
3755
+ "agents": [str(agent) for agent in agents],
3756
+ "token_limit": token_limit,
3757
+ "agent_turn_limit": agent_turn_limit,
3758
+ }
3759
+ return RoomRecord.from_dict(self._post("/rooms", json=body))
3760
+
3761
+ def get_room(self, room_id: str) -> RoomRecord:
3762
+ """Read one room's brief, roster, policy, and status by room/session id."""
3763
+ return RoomRecord.from_dict(self._get(f"/rooms/{quote(room_id, safe='')}"))
3764
+
3765
+ def update_room(
3766
+ self, room_id: str, *, title: str | object = _UNSET, purpose: str | object = _UNSET,
3767
+ style: str | object = _UNSET, rules: Sequence[str] | object = _UNSET,
3768
+ token_limit: int | object = _UNSET, agent_turn_limit: int | object = _UNSET,
3769
+ status: str | object = _UNSET,
3770
+ ) -> RoomRecord:
3771
+ """Owner-edit a room brief, policy knobs, or status.
3772
+
3773
+ Omitted fields are preserved. Supplied ``None`` clears brief text,
3774
+ and restores a policy knob's product default; ``status`` accepts
3775
+ ``live`` or ``archived``. Policy changes take effect at the next
3776
+ authenticated-human-message epoch.
3777
+ """
3778
+ supplied = {
3779
+ "title": title, "purpose": purpose, "style": style, "rules": rules,
3780
+ "token_limit": token_limit, "agent_turn_limit": agent_turn_limit, "status": status,
3781
+ }
3782
+ body = {key: (list(value) if key == "rules" else value)
3783
+ for key, value in supplied.items() if value is not _UNSET}
3784
+ return RoomRecord.from_dict(self._patch(f"/rooms/{quote(room_id, safe='')}", json=body))
3785
+
3786
+ def create_room_message(
3787
+ self, room_id: str, body: str, *, reply_to: str | None = None,
3788
+ ) -> RoomMessage:
3789
+ """Commit one authenticated human message; fanout stays backend-owned.
3790
+
3791
+ The response carries the canonical message identity, its epoch, and
3792
+ the backend's per-agent delivery map. Automatic agent turns are not
3793
+ awaited or relayed here.
3794
+ """
3795
+ payload: dict[str, Any] = {"body": body}
3796
+ if reply_to is not None:
3797
+ payload["reply_to"] = reply_to
3798
+ return RoomMessage.from_dict(
3799
+ self._post(f"/rooms/{quote(room_id, safe='')}/messages", json=payload)
3800
+ )
3801
+
3731
3802
  def redeem_grant_code(self, code: str, *, extend_existing: bool | None = None) -> dict:
3732
3803
  """Redeem a promo/activation grant code via POST /billing/grants/redeem.
3733
3804
 
@@ -0,0 +1,239 @@
1
+ """Backend session catalog types. Source is descriptive, forward-open provenance."""
2
+
3
+ from copy import deepcopy
4
+ from dataclasses import dataclass, field
5
+ from typing import Any
6
+
7
+ from acp import schema
8
+
9
+
10
+ def _parse_session_setup(setup: Any) -> dict[str, Any]:
11
+ if not isinstance(setup, dict) or not isinstance(setup.get("mcpServers"), list):
12
+ raise ValueError("Invalid session setup: expected an object with mcpServers")
13
+ parsed = schema.NewSessionRequest.model_validate(setup)
14
+ # Upstream's forward-compatible parser drops invalid list entries. Recovery
15
+ # must preserve the entire intended list or fail, never silently shorten it.
16
+ if len(parsed.mcp_servers) != len(setup["mcpServers"]):
17
+ raise ValueError("Invalid session setup MCP server entry")
18
+ return deepcopy(setup)
19
+
20
+
21
+ @dataclass
22
+ class SessionSetup:
23
+ """Platform-retained standard ACP setup for one session/agent pair."""
24
+
25
+ session_id: str
26
+ agent_id: str
27
+ setup: dict[str, Any] | None
28
+
29
+ @classmethod
30
+ def from_dict(cls, data: dict[str, Any]) -> "SessionSetup":
31
+ if (not isinstance(data, dict)
32
+ or not isinstance(data.get("session_id"), str)
33
+ or not isinstance(data.get("agent_id"), str)
34
+ or "setup" not in data):
35
+ raise ValueError("Invalid session setup response")
36
+ setup = data["setup"]
37
+ if setup is not None:
38
+ setup = _parse_session_setup(setup)
39
+ return cls(data["session_id"], data["agent_id"], setup)
40
+
41
+
42
+ @dataclass
43
+ class SessionRecord:
44
+ id: str
45
+ source: str | None = None
46
+ summary_text: str | None = None
47
+ summary_keywords: list[str] = field(default_factory=list)
48
+ created_at: str | None = None
49
+ updated_at: str | None = None
50
+ participants: list[dict[str, Any]] = field(default_factory=list)
51
+ import_outcome: dict[str, Any] | None = None
52
+ last_message_id: str | None = None
53
+ message_count: int | None = None
54
+ head_seq: int | None = None
55
+ receipts: list[dict[str, Any]] = field(default_factory=list)
56
+ agent_state: str | None = None # computed per request ("live"|"archived"|"deleted"); None on old servers
57
+ external_url: str | None = None # opaque external reference, independent of source
58
+ meta: dict[str, Any] = field(default_factory=dict)
59
+ mode: str | None = None
60
+
61
+ @classmethod
62
+ def from_dict(cls, data: dict[str, Any]) -> "SessionRecord":
63
+ agent_state = data.get("agentState", data.get("agent_state"))
64
+ return cls(
65
+ id=str(data["id"]),
66
+ meta=deepcopy(data.get("meta", {})),
67
+ mode=data.get("mode"),
68
+ source=data.get("source") if isinstance(data.get("source"), str) else None,
69
+ external_url=data.get("external_url"),
70
+ summary_text=data.get("summary_text"),
71
+ summary_keywords=list(data.get("summary_keywords") or []),
72
+ created_at=data.get("created_at"),
73
+ updated_at=data.get("updated_at"),
74
+ participants=list(data.get("participants") or []),
75
+ import_outcome=data.get("import_outcome") if isinstance(data.get("import_outcome"), dict) else None,
76
+ last_message_id=data.get("last_message_id"),
77
+ message_count=data.get("message_count"),
78
+ head_seq=data.get("head_seq"),
79
+ receipts=list(data.get("receipts") or []),
80
+ agent_state=agent_state if isinstance(agent_state, str) else None,
81
+ )
82
+
83
+
84
+ @dataclass
85
+ class SessionPage:
86
+ items: list[SessionRecord]
87
+ next_cursor: str | None = None
88
+ has_more: bool = False
89
+
90
+ @classmethod
91
+ def from_dict(cls, data: dict[str, Any]) -> "SessionPage":
92
+ return cls(
93
+ items=[SessionRecord.from_dict(row) for row in data.get("items", [])],
94
+ next_cursor=data.get("next_cursor"),
95
+ has_more=data.get("has_more") is True,
96
+ )
97
+
98
+
99
+ @dataclass
100
+ class RoomAgent:
101
+ """One verified agent roster entry on a room read."""
102
+
103
+ agent_id: str
104
+ name: str
105
+ internal_session_id: str | None = None
106
+
107
+ @classmethod
108
+ def from_dict(cls, data: dict[str, Any]) -> "RoomAgent":
109
+ internal_session_id = data.get("internal_session_id")
110
+ if (not isinstance(data, dict)
111
+ or not isinstance(data.get("agent_id"), str)
112
+ or not isinstance(data.get("name"), str)
113
+ or not (internal_session_id is None or isinstance(internal_session_id, str))):
114
+ raise ValueError("Invalid room agent entry")
115
+ return cls(data["agent_id"], data["name"], internal_session_id)
116
+
117
+
118
+ @dataclass
119
+ class RoomRecord:
120
+ """Explicit multiparty room (docs/MULTIPARTY.md) as the product API reads it.
121
+
122
+ ``agent_turn_limit`` is the effective per-epoch allowance the backend
123
+ enforces (product default 25); ``configured_agent_turn_limit`` preserves
124
+ the explicit configuration and is ``None`` when the default is in force.
125
+ """
126
+
127
+ id: str
128
+ kind: str = "room"
129
+ title: str | None = None
130
+ purpose: str = ""
131
+ style: str = ""
132
+ rules: list[str] = field(default_factory=list)
133
+ owner_id: str = ""
134
+ agents: list[RoomAgent] = field(default_factory=list)
135
+ token_limit: int | None = None
136
+ agent_turn_limit: int = 25
137
+ configured_agent_turn_limit: int | None = None
138
+ status: str = "live"
139
+ setup_revision: int = 0
140
+ created_at: str | None = None
141
+ updated_at: str | None = None
142
+
143
+ @classmethod
144
+ def from_dict(cls, data: dict[str, Any]) -> "RoomRecord":
145
+ rules = data.get("rules") if isinstance(data, dict) else None
146
+ agents = data.get("agents") if isinstance(data, dict) else None
147
+ token_limit = data.get("token_limit") if isinstance(data, dict) else None
148
+ agent_turn_limit = data.get("agent_turn_limit") if isinstance(data, dict) else None
149
+ configured = data.get("configured_agent_turn_limit") if isinstance(data, dict) else None
150
+ setup_revision = data.get("setup_revision") if isinstance(data, dict) else None
151
+ if (not isinstance(data, dict)
152
+ or not isinstance(data.get("id"), str)
153
+ or data.get("kind") != "room"
154
+ or not isinstance(data.get("owner_id"), str)
155
+ or not isinstance(data.get("status"), str)
156
+ or not (isinstance(rules, list) and all(isinstance(rule, str) for rule in rules))
157
+ or not (isinstance(agents, list))
158
+ or not (token_limit is None or (isinstance(token_limit, int) and not isinstance(token_limit, bool)))
159
+ or not (isinstance(agent_turn_limit, int) and not isinstance(agent_turn_limit, bool))
160
+ or not (configured is None or (isinstance(configured, int) and not isinstance(configured, bool)))
161
+ or not (isinstance(setup_revision, int) and not isinstance(setup_revision, bool))):
162
+ raise ValueError("Invalid room record response")
163
+ title = data.get("title")
164
+ purpose = data.get("purpose")
165
+ style = data.get("style")
166
+ created_at = data.get("created_at")
167
+ updated_at = data.get("updated_at")
168
+ if not all(value is None or isinstance(value, str) for value in (title, created_at, updated_at)) \
169
+ or not isinstance(purpose, str) or not isinstance(style, str):
170
+ raise ValueError("Invalid room record response")
171
+ return cls(
172
+ id=data["id"],
173
+ kind="room",
174
+ title=title,
175
+ purpose=purpose,
176
+ style=style,
177
+ rules=list(rules),
178
+ owner_id=data["owner_id"],
179
+ agents=[RoomAgent.from_dict(agent) for agent in agents],
180
+ token_limit=token_limit,
181
+ agent_turn_limit=agent_turn_limit,
182
+ configured_agent_turn_limit=configured,
183
+ status=data["status"],
184
+ setup_revision=setup_revision,
185
+ created_at=created_at,
186
+ updated_at=updated_at,
187
+ )
188
+
189
+
190
+ @dataclass
191
+ class RoomMessage:
192
+ """One canonical room message committed by the authenticated owner."""
193
+
194
+ session_id: str
195
+ message_id: str
196
+ seq: int
197
+ epoch_id: str
198
+ sender_id: str
199
+ sender_kind: str
200
+ sender_name: str
201
+ body: str
202
+ reply_to: str | None = None
203
+ created_at: str | None = None
204
+ fanout: dict[str, bool] = field(default_factory=dict)
205
+
206
+ @classmethod
207
+ def from_dict(cls, data: dict[str, Any]) -> "RoomMessage":
208
+ fanout = data.get("fanout") if isinstance(data, dict) else None
209
+ seq = data.get("seq") if isinstance(data, dict) else None
210
+ reply_to = data.get("reply_to") if isinstance(data, dict) else None
211
+ created_at = data.get("created_at") if isinstance(data, dict) else None
212
+ if (not isinstance(data, dict)
213
+ or not isinstance(data.get("session_id"), str)
214
+ or not isinstance(data.get("message_id"), str)
215
+ or not (isinstance(seq, int) and not isinstance(seq, bool))
216
+ or not isinstance(data.get("epoch_id"), str)
217
+ or not isinstance(data.get("sender_id"), str)
218
+ or not isinstance(data.get("sender_kind"), str)
219
+ or not isinstance(data.get("sender_name"), str)
220
+ or not isinstance(data.get("body"), str)
221
+ or not (reply_to is None or isinstance(reply_to, str))
222
+ or not (created_at is None or isinstance(created_at, str))
223
+ or not (isinstance(fanout, dict)
224
+ and all(isinstance(key, str) and isinstance(value, bool)
225
+ for key, value in fanout.items()))):
226
+ raise ValueError("Invalid room message response")
227
+ return cls(
228
+ session_id=data["session_id"],
229
+ message_id=data["message_id"],
230
+ seq=seq,
231
+ epoch_id=data["epoch_id"],
232
+ sender_id=data["sender_id"],
233
+ sender_kind=data["sender_kind"],
234
+ sender_name=data["sender_name"],
235
+ body=data["body"],
236
+ reply_to=reply_to,
237
+ created_at=created_at,
238
+ fanout=dict(fanout),
239
+ )
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "hypercli-sdk"
7
- version = "0.11.0"
7
+ version = "0.11.1"
8
8
  description = "Python SDK for HyperCLI - GPU orchestration and HyperAgent API"
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.10"
@@ -140,6 +140,9 @@ EXPECTED_PUBLIC_SURFACE = frozenset(
140
140
  "RuntimeAuthStatus",
141
141
  "RuntimeIdentity",
142
142
  "RuntimeLoginSession",
143
+ "RoomAgent",
144
+ "RoomMessage",
145
+ "RoomRecord",
143
146
  "SessionPage",
144
147
  "SessionRecord",
145
148
  "SessionSetup",
@@ -0,0 +1,265 @@
1
+ import json
2
+ from unittest.mock import MagicMock
3
+
4
+ import httpx
5
+ import pytest
6
+
7
+ from hypercli import HyperCLI, RoomAgent, RoomMessage, RoomRecord
8
+ from hypercli.agents import Deployments
9
+ from hypercli.http import APIError, HTTPClient
10
+
11
+ ROOM_ID = "2f5d8a10-97c3-4a1e-8b4d-9a2f6c0e7d31"
12
+ AGENT_A = "3f6c9a20-1b4d-4e5f-8a7c-2d0e9f1b3a45"
13
+ AGENT_B = "8d1f2b34-56a7-48b9-9c01-d23e4f5a6b7c"
14
+ OWNER_ID = "81c2f4e6-7a8b-49c0-b1d2-3e4f5a6b7c8d"
15
+
16
+
17
+ def room_row(**overrides):
18
+ row = {
19
+ "id": ROOM_ID,
20
+ "kind": "room",
21
+ "title": "Build triage",
22
+ "purpose": "Investigate CI failures.",
23
+ "style": "Concise technical discussion.",
24
+ "rules": ["Respond with new information only."],
25
+ "owner_id": OWNER_ID,
26
+ "agents": [
27
+ {"agent_id": AGENT_A, "name": "Atlas", "internal_session_id": "claude-9f2e"},
28
+ {"agent_id": AGENT_B, "name": "Maya", "internal_session_id": None},
29
+ ],
30
+ "token_limit": None,
31
+ "agent_turn_limit": 25,
32
+ "configured_agent_turn_limit": None,
33
+ "status": "live",
34
+ "setup_revision": 3,
35
+ "created_at": "2026-11-12T10:00:00Z",
36
+ "updated_at": "2026-11-12T10:00:00Z",
37
+ }
38
+ row.update(overrides)
39
+ return row
40
+
41
+
42
+ def message_row(**overrides):
43
+ row = {
44
+ "session_id": ROOM_ID,
45
+ "message_id": "msg-1",
46
+ "seq": 7,
47
+ "epoch_id": "epoch-1",
48
+ "sender_id": OWNER_ID,
49
+ "sender_kind": "user",
50
+ "sender_name": "Dmitry",
51
+ "body": "Can you look at the build failure?",
52
+ "reply_to": None,
53
+ "created_at": "2026-11-12T10:05:00Z",
54
+ "fanout": {AGENT_A: True, AGENT_B: False},
55
+ }
56
+ row.update(overrides)
57
+ return row
58
+
59
+
60
+ def patch_transport(monkeypatch, responses):
61
+ """Route by (method, path); responses is a dict of path -> payload or status."""
62
+ requests = []
63
+
64
+ def send(self, request, **kwargs):
65
+ requests.append(request)
66
+ key = (request.method, request.url.path)
67
+ if key not in responses:
68
+ return httpx.Response(404, json={"detail": "no route"}, request=request)
69
+ reply = responses[key]
70
+ if isinstance(reply, httpx.Response):
71
+ return reply
72
+ return httpx.Response(200, json=reply, request=request)
73
+
74
+ monkeypatch.setattr(httpx.Client, "send", send)
75
+ return requests
76
+
77
+
78
+ def make_api():
79
+ return HyperCLI(api_key="caller-key", api_url="https://example.com").deployments
80
+
81
+
82
+ def test_create_room_exact_wire_and_default_readback(monkeypatch):
83
+ requests = patch_transport(monkeypatch, {("POST", "/agents/rooms"): room_row()})
84
+ room = make_api().create_room([AGENT_A, AGENT_B], title="Build triage",
85
+ purpose="Investigate CI failures.",
86
+ style="Concise technical discussion.",
87
+ rules=["Respond with new information only."])
88
+ assert len(requests) == 1
89
+ request = requests[0]
90
+ assert str(request.url) == "https://example.com/agents/rooms"
91
+ assert request.method == "POST"
92
+ assert request.headers["Authorization"] == "Bearer caller-key"
93
+ assert json.loads(request.content) == {
94
+ "title": "Build triage",
95
+ "purpose": "Investigate CI failures.",
96
+ "style": "Concise technical discussion.",
97
+ "rules": ["Respond with new information only."],
98
+ "agents": [AGENT_A, AGENT_B],
99
+ "token_limit": None,
100
+ "agent_turn_limit": None,
101
+ }
102
+ assert room == RoomRecord(
103
+ id=ROOM_ID, title="Build triage", purpose="Investigate CI failures.",
104
+ style="Concise technical discussion.", rules=["Respond with new information only."],
105
+ owner_id=OWNER_ID,
106
+ agents=[RoomAgent(AGENT_A, "Atlas", "claude-9f2e"), RoomAgent(AGENT_B, "Maya")],
107
+ token_limit=None, agent_turn_limit=25, configured_agent_turn_limit=None,
108
+ status="live", setup_revision=3,
109
+ created_at="2026-11-12T10:00:00Z", updated_at="2026-11-12T10:00:00Z",
110
+ )
111
+
112
+
113
+ def test_create_room_defaults_send_documented_body(monkeypatch):
114
+ requests = patch_transport(monkeypatch, {("POST", "/agents/rooms"): room_row()})
115
+ make_api().create_room([AGENT_A])
116
+ assert json.loads(requests[0].content) == {
117
+ "title": None, "purpose": "", "style": "", "rules": [],
118
+ "agents": [AGENT_A], "token_limit": None, "agent_turn_limit": None,
119
+ }
120
+
121
+
122
+ def test_create_room_passes_explicit_policy_knobs(monkeypatch):
123
+ requests = patch_transport(monkeypatch, {
124
+ ("POST", "/agents/rooms"): room_row(
125
+ token_limit=100000, agent_turn_limit=0, configured_agent_turn_limit=0,
126
+ ),
127
+ })
128
+ room = make_api().create_room([AGENT_A], token_limit=100000, agent_turn_limit=0)
129
+ body = json.loads(requests[0].content)
130
+ assert body["token_limit"] == 100000 and body["agent_turn_limit"] == 0
131
+ assert room.token_limit == 100000
132
+ assert room.agent_turn_limit == 0 and room.configured_agent_turn_limit == 0
133
+
134
+
135
+ def test_get_room_exact_wire(monkeypatch):
136
+ requests = patch_transport(monkeypatch, {("GET", f"/agents/rooms/{ROOM_ID}"): room_row()})
137
+ room = make_api().get_room(ROOM_ID)
138
+ assert len(requests) == 1
139
+ request = requests[0]
140
+ assert str(request.url) == f"https://example.com/agents/rooms/{ROOM_ID}"
141
+ assert request.method == "GET" and request.content == b""
142
+ assert request.headers["Authorization"] == "Bearer caller-key"
143
+ assert room.id == ROOM_ID and room.kind == "room"
144
+ assert room.status == "live"
145
+
146
+
147
+ def test_update_room_omits_unsupplied_fields(monkeypatch):
148
+ requests = patch_transport(
149
+ monkeypatch,
150
+ {("PATCH", f"/agents/rooms/{ROOM_ID}"): room_row(title="New focus", setup_revision=4)},
151
+ )
152
+ room = make_api().update_room(ROOM_ID, title="New focus", status="archived")
153
+ assert json.loads(requests[0].content) == {"title": "New focus", "status": "archived"}
154
+ assert requests[0].method == "PATCH"
155
+ assert room.title == "New focus" and room.setup_revision == 4
156
+
157
+
158
+ @pytest.mark.parametrize("patch,expected", [
159
+ ({"purpose": None}, {"purpose": None}),
160
+ ({"rules": []}, {"rules": []}),
161
+ ({"token_limit": None}, {"token_limit": None}),
162
+ ({"agent_turn_limit": 5}, {"agent_turn_limit": 5}),
163
+ ])
164
+ def test_update_room_null_semantics(monkeypatch, patch, expected):
165
+ requests = patch_transport(monkeypatch, {("PATCH", f"/agents/rooms/{ROOM_ID}"): room_row()})
166
+ make_api().update_room(ROOM_ID, **patch)
167
+ assert json.loads(requests[0].content) == expected
168
+
169
+
170
+ def test_update_room_sends_empty_patch_when_nothing_supplied(monkeypatch):
171
+ requests = patch_transport(monkeypatch, {("PATCH", f"/agents/rooms/{ROOM_ID}"): room_row()})
172
+ make_api().update_room(ROOM_ID)
173
+ assert json.loads(requests[0].content) == {}
174
+
175
+
176
+ def test_create_room_message_exact_wire_and_readback(monkeypatch):
177
+ requests = patch_transport(
178
+ monkeypatch, {("POST", f"/agents/rooms/{ROOM_ID}/messages"): message_row(reply_to="msg-0")},
179
+ )
180
+ message = make_api().create_room_message(
181
+ ROOM_ID, "Can you look at the build failure?", reply_to="msg-0",
182
+ )
183
+ assert len(requests) == 1
184
+ request = requests[0]
185
+ assert str(request.url) == f"https://example.com/agents/rooms/{ROOM_ID}/messages"
186
+ assert request.method == "POST"
187
+ assert json.loads(request.content) == {
188
+ "body": "Can you look at the build failure?", "reply_to": "msg-0",
189
+ }
190
+ assert message == RoomMessage(
191
+ session_id=ROOM_ID, message_id="msg-1", seq=7, epoch_id="epoch-1",
192
+ sender_id=OWNER_ID, sender_kind="user", sender_name="Dmitry",
193
+ body="Can you look at the build failure?", reply_to="msg-0",
194
+ created_at="2026-11-12T10:05:00Z", fanout={AGENT_A: True, AGENT_B: False},
195
+ )
196
+
197
+
198
+ def test_create_room_message_omits_absent_reply_to(monkeypatch):
199
+ requests = patch_transport(
200
+ monkeypatch, {("POST", f"/agents/rooms/{ROOM_ID}/messages"): message_row()},
201
+ )
202
+ make_api().create_room_message(ROOM_ID, "hello")
203
+ assert json.loads(requests[0].content) == {"body": "hello"}
204
+
205
+
206
+ def test_room_message_encodes_odd_room_ids(monkeypatch):
207
+ requests = []
208
+
209
+ def send(self, request, **kwargs):
210
+ requests.append(request)
211
+ return httpx.Response(200, json=message_row(), request=request)
212
+
213
+ monkeypatch.setattr(httpx.Client, "send", send)
214
+ make_api().create_room_message("platform/odd id?#%", "hello")
215
+ assert str(requests[0].url) == \
216
+ "https://example.com/agents/rooms/platform%2Fodd%20id%3F%23%25/messages"
217
+
218
+
219
+ @pytest.mark.parametrize("status", [401, 403, 404, 422])
220
+ def test_room_errors_propagate_without_fallback(monkeypatch, status):
221
+ denied = httpx.Response(status, json={"detail": "Only the room owner may manage this room"})
222
+ requests = patch_transport(monkeypatch, {
223
+ ("POST", "/agents/rooms"): denied,
224
+ ("GET", f"/agents/rooms/{ROOM_ID}"): denied,
225
+ ("PATCH", f"/agents/rooms/{ROOM_ID}"): denied,
226
+ ("POST", f"/agents/rooms/{ROOM_ID}/messages"): denied,
227
+ })
228
+ api = make_api()
229
+ with pytest.raises(APIError) as exc:
230
+ api.create_room([AGENT_A])
231
+ assert exc.value.status_code == status
232
+ with pytest.raises(APIError):
233
+ api.get_room(ROOM_ID)
234
+ with pytest.raises(APIError):
235
+ api.update_room(ROOM_ID, title="x")
236
+ with pytest.raises(APIError):
237
+ api.create_room_message(ROOM_ID, "hello")
238
+ assert len(requests) == 4
239
+
240
+
241
+ @pytest.mark.parametrize("overrides", [
242
+ {"kind": "dm"}, {"id": None}, {"agent_turn_limit": None}, {"setup_revision": "3"},
243
+ {"token_limit": True}, {"rules": "be nice"}, {"agents": [{"agent_id": AGENT_A}]},
244
+ ])
245
+ def test_room_record_rejects_malformed_responses(overrides):
246
+ with pytest.raises(ValueError):
247
+ RoomRecord.from_dict(room_row(**overrides))
248
+
249
+
250
+ @pytest.mark.parametrize("overrides", [
251
+ {"seq": "7"}, {"fanout": {AGENT_A: "yes"}}, {"body": None}, {"sender_kind": None},
252
+ ])
253
+ def test_room_message_rejects_malformed_responses(overrides):
254
+ with pytest.raises(ValueError):
255
+ RoomMessage.from_dict(message_row(**overrides))
256
+
257
+
258
+ def test_room_helpers_use_the_sessions_transport_scope():
259
+ """Rooms ride the same agents API base and user auth as the DM session reads."""
260
+ http = MagicMock(spec=HTTPClient)
261
+ http.api_key = "test"
262
+ api = Deployments(http, api_base="https://example.com/agents")
263
+ api._get = MagicMock(return_value=room_row())
264
+ api.get_room("room-id")
265
+ api._get.assert_called_once_with("/rooms/room-id")
@@ -1,96 +0,0 @@
1
- """Backend session catalog types. Source is descriptive, forward-open provenance."""
2
-
3
- from copy import deepcopy
4
- from dataclasses import dataclass, field
5
- from typing import Any
6
-
7
- from acp import schema
8
-
9
-
10
- def _parse_session_setup(setup: Any) -> dict[str, Any]:
11
- if not isinstance(setup, dict) or not isinstance(setup.get("mcpServers"), list):
12
- raise ValueError("Invalid session setup: expected an object with mcpServers")
13
- parsed = schema.NewSessionRequest.model_validate(setup)
14
- # Upstream's forward-compatible parser drops invalid list entries. Recovery
15
- # must preserve the entire intended list or fail, never silently shorten it.
16
- if len(parsed.mcp_servers) != len(setup["mcpServers"]):
17
- raise ValueError("Invalid session setup MCP server entry")
18
- return deepcopy(setup)
19
-
20
-
21
- @dataclass
22
- class SessionSetup:
23
- """Platform-retained standard ACP setup for one session/agent pair."""
24
-
25
- session_id: str
26
- agent_id: str
27
- setup: dict[str, Any] | None
28
-
29
- @classmethod
30
- def from_dict(cls, data: dict[str, Any]) -> "SessionSetup":
31
- if (not isinstance(data, dict)
32
- or not isinstance(data.get("session_id"), str)
33
- or not isinstance(data.get("agent_id"), str)
34
- or "setup" not in data):
35
- raise ValueError("Invalid session setup response")
36
- setup = data["setup"]
37
- if setup is not None:
38
- setup = _parse_session_setup(setup)
39
- return cls(data["session_id"], data["agent_id"], setup)
40
-
41
-
42
- @dataclass
43
- class SessionRecord:
44
- id: str
45
- source: str | None = None
46
- summary_text: str | None = None
47
- summary_keywords: list[str] = field(default_factory=list)
48
- created_at: str | None = None
49
- updated_at: str | None = None
50
- participants: list[dict[str, Any]] = field(default_factory=list)
51
- import_outcome: dict[str, Any] | None = None
52
- last_message_id: str | None = None
53
- message_count: int | None = None
54
- head_seq: int | None = None
55
- receipts: list[dict[str, Any]] = field(default_factory=list)
56
- agent_state: str | None = None # computed per request ("live"|"archived"|"deleted"); None on old servers
57
- external_url: str | None = None # opaque external reference, independent of source
58
- meta: dict[str, Any] = field(default_factory=dict)
59
- mode: str | None = None
60
-
61
- @classmethod
62
- def from_dict(cls, data: dict[str, Any]) -> "SessionRecord":
63
- agent_state = data.get("agentState", data.get("agent_state"))
64
- return cls(
65
- id=str(data["id"]),
66
- meta=deepcopy(data.get("meta", {})),
67
- mode=data.get("mode"),
68
- source=data.get("source") if isinstance(data.get("source"), str) else None,
69
- external_url=data.get("external_url"),
70
- summary_text=data.get("summary_text"),
71
- summary_keywords=list(data.get("summary_keywords") or []),
72
- created_at=data.get("created_at"),
73
- updated_at=data.get("updated_at"),
74
- participants=list(data.get("participants") or []),
75
- import_outcome=data.get("import_outcome") if isinstance(data.get("import_outcome"), dict) else None,
76
- last_message_id=data.get("last_message_id"),
77
- message_count=data.get("message_count"),
78
- head_seq=data.get("head_seq"),
79
- receipts=list(data.get("receipts") or []),
80
- agent_state=agent_state if isinstance(agent_state, str) else None,
81
- )
82
-
83
-
84
- @dataclass
85
- class SessionPage:
86
- items: list[SessionRecord]
87
- next_cursor: str | None = None
88
- has_more: bool = False
89
-
90
- @classmethod
91
- def from_dict(cls, data: dict[str, Any]) -> "SessionPage":
92
- return cls(
93
- items=[SessionRecord.from_dict(row) for row in data.get("items", [])],
94
- next_cursor=data.get("next_cursor"),
95
- has_more=data.get("has_more") is True,
96
- )
File without changes
File without changes