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.
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/PKG-INFO +12 -1
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/README.md +11 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/hypercli/__init__.py +8 -2
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/hypercli/agents.py +44 -7
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/hypercli/client.py +3 -1
- hypercli_sdk-0.11.2/hypercli/personas.py +36 -0
- hypercli_sdk-0.11.2/hypercli/session_subscription.py +120 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/hypercli/sessions.py +56 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/hypercli/user.py +10 -1
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/pyproject.toml +1 -1
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/test_coding_agents.py +2 -6
- hypercli_sdk-0.11.2/tests/test_personas.py +91 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/test_public_surface.py +5 -0
- hypercli_sdk-0.11.2/tests/test_sessions.py +460 -0
- hypercli_sdk-0.11.1/tests/test_sessions.py +0 -213
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/.gitignore +0 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/hypercli/acp.py +0 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/hypercli/agent.py +0 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/hypercli/billing.py +0 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/hypercli/chat_integrations.py +0 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/hypercli/config.py +0 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/hypercli/files.py +0 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/hypercli/http.py +0 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/hypercli/instances.py +0 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/hypercli/job/__init__.py +0 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/hypercli/job/base.py +0 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/hypercli/job/comfyui.py +0 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/hypercli/job/gradio.py +0 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/hypercli/jobs.py +0 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/hypercli/keys.py +0 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/hypercli/logs.py +0 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/hypercli/mcp.py +0 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/hypercli/models.py +0 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/hypercli/renders.py +0 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/hypercli/routines.py +0 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/hypercli/runners.py +0 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/hypercli/shell.py +0 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/hypercli/voice.py +0 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/hypercli/voice_stream.py +0 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/hypercli/voice_transcription.py +0 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/hypercli/workspaces.py +0 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/hypercli/x402.py +0 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/integration/conftest.py +0 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/integration/test_agents.py +0 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/integration/test_auth.py +0 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/integration/test_billing.py +0 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/integration/test_instances.py +0 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/integration/test_jobs_dryrun.py +0 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/integration/test_keys.py +0 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/integration/test_renders.py +0 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/test_acp.py +0 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/test_agent_files_source.py +0 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/test_agent_lifecycle.py +0 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/test_agents.py +0 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/test_apply_params.py +0 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/test_bootstrap_agents_e2e_user.py +0 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/test_bootstrap_console_test_key.py +0 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/test_bootstrap_dev_test_keys.py +0 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/test_chat_integrations.py +0 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/test_claw.py +0 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/test_config.py +0 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/test_exec_shell_dryrun.py +0 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/test_file_transport.py +0 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/test_graph_to_api.py +0 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/test_http.py +0 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/test_jobs.py +0 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/test_keys.py +0 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/test_models.py +0 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/test_parity_audit.py +0 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/test_render_catalog.py +0 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/test_renders_subscription.py +0 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/test_repository_integrity.py +0 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/test_rooms.py +0 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/test_routines.py +0 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/test_runner_control_url.py +0 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/test_runner_placement.py +0 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/test_runners.py +0 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/test_status.py +0 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/test_voice.py +0 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/test_voice_stream.py +0 -0
- {hypercli_sdk-0.11.1 → hypercli_sdk-0.11.2}/tests/test_voice_transcription.py +0 -0
- {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.
|
|
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.
|
|
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",
|
|
273
|
-
"claude-code": (".claude", ".claude.json"
|
|
274
|
-
"goose": (".goose",
|
|
275
|
-
"kimi-code": (".kimi-code",
|
|
276
|
-
"pi": (".pi",
|
|
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"""
|
|
@@ -421,10 +421,8 @@ class TestCreateAgentCodingRuntimes:
|
|
|
421
421
|
|
|
422
422
|
body = posts[0][1]
|
|
423
423
|
assert "sync_exclude" not in body
|
|
424
|
-
assert
|
|
425
|
-
|
|
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",
|