healthcloud-cli 3.7.5__tar.gz → 3.7.7__tar.gz

{healthcloud_cli-3.7.5 → healthcloud_cli-3.7.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: healthcloud-cli
-Version: 3.7.5
+Version: 3.7.7
 Summary: Command-line interface for the HealthCloud MCP gateway, generated from the shared MCP tool manifest.
 Project-URL: Issues, https://github.com/healthcloudservices/healthcloud-services/issues
 Project-URL: Repository, https://github.com/healthcloudservices/healthcloud-services
@@ -1082,9 +1082,14 @@ uv run --frozen hc ams sessions messages add --environment dev --tenant-id TENAN
 
 - `list` emits `operation: "sessions.list"`, `data.sessions` (bounded projections
   of session ID, agent ID, operation, mode, status and audit timestamps) and a
-  `page` block (`{"kind": "limit", "limit": N, "returned_count": N,
-  "continuation": null}`). `get` emits `operation: "sessions.get"` and
-  `data.session`. The projections never include the session's protected
+  `page` block. These routes page with a limit only, so the block always says
+  which limit was in force: with `--limit N` it is
+  `{"kind": "limit", "limit": N, "returned_count": N, "continuation": null}`,
+  and without it the server's own default page was applied, which the block
+  reports as `{"kind": "server_default", "server_default_limit": 50,
+  "returned_count": N, "continuation": null}` (50 sessions, 100 messages) — so
+  a truncated page is never mistaken for a complete list. `get` emits
+  `operation: "sessions.get"` and `data.session`. The projections never include the session's protected
   `initial_prompt`, tenant or user identity, or arbitrary response fields.
 - Default `pretty` output prints `list` as a table with honest headers —
   `ID`, `AGENT ID`, `OPERATION`, `STATUS`, `EXPIRES AT` for sessions and `ID`,
@@ -1099,8 +1104,12 @@ uv run --frozen hc ams sessions messages add --environment dev --tenant-id TENAN
   the envelope carries the server's authoritative readback:
   `operation: "sessions.create"` with `data.session`, and
   `operation: "sessions.messages.add"` with `data.message` (message ID, role,
-  mode, plan ID, model, timestamps) plus `data.idempotency_key` when a key was
-  supplied. Protected free text — `--initial-prompt` and `--content` — is sent to
+  mode, plan ID, model, timestamps) plus `data.idempotency_key` — the key the
+  server read back, when the returned message carries one. When the readback
+  does not echo a key, the field is omitted: the envelope never asserts a
+  key→message association the server did not confirm. An `--idempotency-key`
+  longer than 128 characters (or an empty one) is refused locally with a
+  `validation` error naming the flag, before anything is sent. Protected free text — `--initial-prompt` and `--content` — is sent to
   the server but never appears in the envelope, a refusal, a diagnostic or a log.
 - The protected free text can also arrive from an owner-only file, which keeps it
   out of the command line entirely (argv, the process table under
@@ -1129,18 +1138,24 @@ uv run --frozen hc ams sessions messages add --environment dev --tenant-id TENAN
 - `--initial-prompt` becomes the session's first `user` message in the same
   server transaction; `hc ams sessions messages list` shows it afterwards.
 - `--mode implement` is not available from the server yet: `create` reports one
-  `unsupported` refusal (the server answers 501) and creates nothing. A message
+  `unsupported` refusal (the server answers 501) and creates nothing, and a
+  `messages add` the server answers 501 for is the same `unsupported` refusal
+  with no message added. Both refusals report the 501 the server actually sent
+  and name implement mode as the documented reason, rather than asserting the
+  requested mode was the cause. A message
   whose `--mode` differs from its session's mode is refused by the server with
-  409 and reported as one write-worded `conflict` refusal that says a message's
-  mode must match its session's mode and points at `hc ams sessions get`; no
-  message is added, and the read-era conflict wording is never used.
+  409 and reported as one write-worded `conflict` refusal that names the
+  session, mentions a mode mismatch as one possible cause, and points at
+  `hc ams sessions get`; no message is added, and the read-era conflict wording
+  is never used.
 - A missing, expired or other user's session is a `not_found` refusal naming the
   session on `get`, `messages list` and `messages add`; on `create`, a 404 names
   the requested `--agent-id`.
 - Messages with an `--idempotency-key` are replay-safe: the server answers 201
   with the existing message instead of inserting a second one, and the command
   reports that message (its original ID) — a replay is never reported as a new
-  write, and the command itself never re-sends a write.
+  write, and the command itself never re-sends a write. The envelope echoes the
+  server's read-back key, never a key the server did not confirm.
 - If the transport times out or the connection drops mid-write, the write's
   outcome is unknown: the CLI reports one `transport` error whose message says so
   and points at `hc ams sessions list`/`hc ams sessions messages list` before
@@ -1149,8 +1164,15 @@ uv run --frozen hc ams sessions messages add --environment dev --tenant-id TENAN
   landed write is never reported as stopped.
 - Reads refuse target files, root credentials or base URLs, raw output, blank or
   dot-segment session IDs, out-of-range limits, and installed SDKs without the
-  session list/get and message list/add methods before tenant-admin login or any
-  read. The existing `hc ams plan|show|apply|restore` tuning commands and their
+  session list/get and message list methods before tenant-admin login or any
+  read. `messages list` needs only `messages.list` — the write method `add` is
+  not required for the read. The writes check their own methods in the same
+  preflight — each command requires exactly the write method it calls, so
+  `create` refuses an installed SDK without `sessions.create` and `messages add`
+  one without `messages.add` before tenant-admin login and before any read or
+  write, and neither is refused for the write the other command performs. A single-object route whose 2xx body is not a JSON
+  object is refused as a `validation` error, never reported as an internal
+  failure. The existing `hc ams plan|show|apply|restore` tuning commands and their
   signatures are unchanged.
 - These session and message commands do not attach files, apply or roll back
   configuration, or send session history to a model. Plan review is its own
@@ -1241,6 +1263,9 @@ uv run --frozen hc ams sessions plans reconcile --environment dev --tenant-id TE
   message write, no `PUT` and no apply. The server runs the planner once. It
   requires a saved `hc login` session and reports
   `operation: "sessions.plans.generate"` with `data.plan` and `data.out`.
+  An `--idempotency-key` longer than 128 characters (or an empty one) is
+  refused locally with a `validation` error naming the flag, before anything
+  is sent.
   `get` sends exactly one `GET /vibecoder/plans/PLAN_ID` and reports
   `operation: "sessions.plans.get"`; a reload is immutable, so it returns the
   same `plan_hash` and diff however the session changed afterwards. `get` is a

{healthcloud_cli-3.7.5 → healthcloud_cli-3.7.7}/README.md

@@ -1064,9 +1064,14 @@ uv run --frozen hc ams sessions messages add --environment dev --tenant-id TENAN
 
 - `list` emits `operation: "sessions.list"`, `data.sessions` (bounded projections
   of session ID, agent ID, operation, mode, status and audit timestamps) and a
-  `page` block (`{"kind": "limit", "limit": N, "returned_count": N,
-  "continuation": null}`). `get` emits `operation: "sessions.get"` and
-  `data.session`. The projections never include the session's protected
+  `page` block. These routes page with a limit only, so the block always says
+  which limit was in force: with `--limit N` it is
+  `{"kind": "limit", "limit": N, "returned_count": N, "continuation": null}`,
+  and without it the server's own default page was applied, which the block
+  reports as `{"kind": "server_default", "server_default_limit": 50,
+  "returned_count": N, "continuation": null}` (50 sessions, 100 messages) — so
+  a truncated page is never mistaken for a complete list. `get` emits
+  `operation: "sessions.get"` and `data.session`. The projections never include the session's protected
   `initial_prompt`, tenant or user identity, or arbitrary response fields.
 - Default `pretty` output prints `list` as a table with honest headers —
   `ID`, `AGENT ID`, `OPERATION`, `STATUS`, `EXPIRES AT` for sessions and `ID`,
@@ -1081,8 +1086,12 @@ uv run --frozen hc ams sessions messages add --environment dev --tenant-id TENAN
   the envelope carries the server's authoritative readback:
   `operation: "sessions.create"` with `data.session`, and
   `operation: "sessions.messages.add"` with `data.message` (message ID, role,
-  mode, plan ID, model, timestamps) plus `data.idempotency_key` when a key was
-  supplied. Protected free text — `--initial-prompt` and `--content` — is sent to
+  mode, plan ID, model, timestamps) plus `data.idempotency_key` — the key the
+  server read back, when the returned message carries one. When the readback
+  does not echo a key, the field is omitted: the envelope never asserts a
+  key→message association the server did not confirm. An `--idempotency-key`
+  longer than 128 characters (or an empty one) is refused locally with a
+  `validation` error naming the flag, before anything is sent. Protected free text — `--initial-prompt` and `--content` — is sent to
   the server but never appears in the envelope, a refusal, a diagnostic or a log.
 - The protected free text can also arrive from an owner-only file, which keeps it
   out of the command line entirely (argv, the process table under
@@ -1111,18 +1120,24 @@ uv run --frozen hc ams sessions messages add --environment dev --tenant-id TENAN
 - `--initial-prompt` becomes the session's first `user` message in the same
   server transaction; `hc ams sessions messages list` shows it afterwards.
 - `--mode implement` is not available from the server yet: `create` reports one
-  `unsupported` refusal (the server answers 501) and creates nothing. A message
+  `unsupported` refusal (the server answers 501) and creates nothing, and a
+  `messages add` the server answers 501 for is the same `unsupported` refusal
+  with no message added. Both refusals report the 501 the server actually sent
+  and name implement mode as the documented reason, rather than asserting the
+  requested mode was the cause. A message
   whose `--mode` differs from its session's mode is refused by the server with
-  409 and reported as one write-worded `conflict` refusal that says a message's
-  mode must match its session's mode and points at `hc ams sessions get`; no
-  message is added, and the read-era conflict wording is never used.
+  409 and reported as one write-worded `conflict` refusal that names the
+  session, mentions a mode mismatch as one possible cause, and points at
+  `hc ams sessions get`; no message is added, and the read-era conflict wording
+  is never used.
 - A missing, expired or other user's session is a `not_found` refusal naming the
   session on `get`, `messages list` and `messages add`; on `create`, a 404 names
   the requested `--agent-id`.
 - Messages with an `--idempotency-key` are replay-safe: the server answers 201
   with the existing message instead of inserting a second one, and the command
   reports that message (its original ID) — a replay is never reported as a new
-  write, and the command itself never re-sends a write.
+  write, and the command itself never re-sends a write. The envelope echoes the
+  server's read-back key, never a key the server did not confirm.
 - If the transport times out or the connection drops mid-write, the write's
   outcome is unknown: the CLI reports one `transport` error whose message says so
   and points at `hc ams sessions list`/`hc ams sessions messages list` before
@@ -1131,8 +1146,15 @@ uv run --frozen hc ams sessions messages add --environment dev --tenant-id TENAN
   landed write is never reported as stopped.
 - Reads refuse target files, root credentials or base URLs, raw output, blank or
   dot-segment session IDs, out-of-range limits, and installed SDKs without the
-  session list/get and message list/add methods before tenant-admin login or any
-  read. The existing `hc ams plan|show|apply|restore` tuning commands and their
+  session list/get and message list methods before tenant-admin login or any
+  read. `messages list` needs only `messages.list` — the write method `add` is
+  not required for the read. The writes check their own methods in the same
+  preflight — each command requires exactly the write method it calls, so
+  `create` refuses an installed SDK without `sessions.create` and `messages add`
+  one without `messages.add` before tenant-admin login and before any read or
+  write, and neither is refused for the write the other command performs. A single-object route whose 2xx body is not a JSON
+  object is refused as a `validation` error, never reported as an internal
+  failure. The existing `hc ams plan|show|apply|restore` tuning commands and their
   signatures are unchanged.
 - These session and message commands do not attach files, apply or roll back
   configuration, or send session history to a model. Plan review is its own
@@ -1223,6 +1245,9 @@ uv run --frozen hc ams sessions plans reconcile --environment dev --tenant-id TE
   message write, no `PUT` and no apply. The server runs the planner once. It
   requires a saved `hc login` session and reports
   `operation: "sessions.plans.generate"` with `data.plan` and `data.out`.
+  An `--idempotency-key` longer than 128 characters (or an empty one) is
+  refused locally with a `validation` error naming the flag, before anything
+  is sent.
   `get` sends exactly one `GET /vibecoder/plans/PLAN_ID` and reports
   `operation: "sessions.plans.get"`; a reload is immutable, so it returns the
   same `plan_hash` and diff however the session changed afterwards. `get` is a

{healthcloud_cli-3.7.5 → healthcloud_cli-3.7.7}/healthcloud_cli/ams/context.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from collections.abc import Callable
+from collections.abc import Callable, Sequence
 from contextlib import AbstractContextManager
 from dataclasses import dataclass
 from pathlib import Path
@@ -236,8 +236,20 @@ def preflight_policies(invocation: AmsContext, target: TenantTarget) -> None:
         sdk.close()
 
 
-def preflight_sessions(invocation: AmsContext, target: TenantTarget) -> None:
-    """Validate local session-read compatibility before login or any read."""
+def preflight_sessions(
+    invocation: AmsContext,
+    target: TenantTarget,
+    *,
+    write_methods: Sequence[str] = (),
+) -> None:
+    """Validate local session compatibility before login or any request.
+
+    ``write_methods`` names exactly the write methods the calling command will
+    call, as ``"<resource>.<method>"`` (``sessions.create``, ``messages.add``),
+    so a write command is refused here — before tenant-admin login and before any
+    read or write — only for a method it actually needs; a write it never
+    performs is never required of the installed SDK.
+    """
 
     _check_root(invocation)
     if invocation.target_file is not None:
@@ -245,12 +257,16 @@ def preflight_sessions(invocation: AmsContext, target: TenantTarget) -> None:
     sdk = _public_sdk(target.environment, target.tenant_id)
     try:
         resource = getattr(getattr(sdk, "ams_admin", None), "sessions", None)
-        if (
-            resource is None
-            or not callable(getattr(resource, "list", None))
-            or not callable(getattr(resource, "get", None))
-            or not callable(getattr(getattr(resource, "messages", None), "list", None))
-        ):
+        messages = getattr(resource, "messages", None)
+        resources = {"sessions": resource, "messages": messages}
+        required = (resource, "list"), (resource, "get"), (messages, "list")
+        missing = any(not callable(getattr(holder, method, None)) for holder, method in required)
+        for qualified in write_methods:
+            owner, _, method = qualified.partition(".")
+            holder = resources.get(owner)
+            if not method or not callable(getattr(holder, method, None)):
+                missing = True
+        if missing:
             raise click.ClickException(
                 "SDK missing ams_admin sessions; use the reviewed SDK version required by this CLI."
             )

{healthcloud_cli-3.7.5 → healthcloud_cli-3.7.7}/healthcloud_cli/ams/sessions/commands.py

@@ -125,7 +125,7 @@ def create_create_command(dependencies: AmsDependencies) -> click.Command:
             _require_login()
             target = resolve_tenant_target(environment, tenant_id)
             target_data.update(environment=target.environment, tenant_id=target.tenant_id)
-            preflight_sessions(invocation, target)
+            preflight_sessions(invocation, target, write_methods=("sessions.create",))
             return create_session(
                 dependencies,
                 target,
@@ -561,7 +561,7 @@ def create_messages_add_command(dependencies: AmsDependencies) -> click.Command:
             _require_login()
             target = resolve_tenant_target(environment, tenant_id)
             target_data.update(environment=target.environment, tenant_id=target.tenant_id)
-            preflight_sessions(invocation, target)
+            preflight_sessions(invocation, target, write_methods=("messages.add",))
             return add_message(
                 dependencies,
                 target,

{healthcloud_cli-3.7.5 → healthcloud_cli-3.7.7}/healthcloud_cli/ams/sessions/operations.py

@@ -25,7 +25,11 @@ from .projections import (
 )
 
 SESSION_LIMIT_MAX = 100
+# The server's own defaults when ``--limit`` is omitted: an omitted limit is a
+# real, truncating page, so the envelope reports which default was applied.
+SESSION_LIMIT_DEFAULT = 50
 MESSAGE_LIMIT_MAX = 200
+MESSAGE_LIMIT_DEFAULT = 100
 # Mirror the server's own bounds so an obviously unacceptable file is never
 # put on the wire; the server's refusal still wins when it disagrees.
 ATTACHMENT_MAX_BYTES = 5 * 1024 * 1024
@@ -87,6 +91,28 @@ def _session_id(value: str) -> str:
     return value
 
 
+IDEMPOTENCY_KEY_MAX_CHARS = 128
+
+
+def _idempotency_key(value, refuse):
+    """Mirror the SDK's 128-character bound locally (the help text advertises it).
+
+    Refused before login or any request, so the bound holds regardless of the
+    installed SDK version. A non-empty string within the bound passes through
+    unchanged; the caller keeps its own refusal class (message write vs plan
+    review).
+    """
+    if value is None:
+        return None
+    if not isinstance(value, str) or not value or len(value) > IDEMPOTENCY_KEY_MAX_CHARS:
+        raise refuse(
+            "validation",
+            f"--idempotency-key must be a non-empty string of at most {IDEMPOTENCY_KEY_MAX_CHARS} "
+            "characters; nothing was sent.",
+        )
+    return value
+
+
 def _limit(value: int | None, maximum: int, name: str) -> int | None:
     if value is None:
         return None
@@ -540,6 +566,26 @@ def _identity(session, target: TenantTarget, session_id: str | None) -> None:
         )
 
 
+def _page(limit: int | None, server_default: int, returned: int) -> dict:
+    """The page block, honest about an omitted ``--limit``.
+
+    These routes page with a limit only: an omitted limit is not "unpaged", it
+    is the server's own default page, which can truncate the list. The block
+    therefore reports either the limit that was sent, or the server default
+    that was applied instead, so a consumer can always tell whether more rows
+    may exist.
+    """
+
+    if limit is None:
+        return {
+            "kind": "server_default",
+            "server_default_limit": server_default,
+            "returned_count": returned,
+            "continuation": None,
+        }
+    return {"kind": "limit", "limit": limit, "returned_count": returned, "continuation": None}
+
+
 def list_sessions(dependencies: AmsDependencies, target: TenantTarget, *, limit: int | None = None) -> dict:
     """`hc ams sessions list`: the caller's non-expired sessions, newest first."""
 
@@ -554,12 +600,7 @@ def list_sessions(dependencies: AmsDependencies, target: TenantTarget, *, limit:
         _target(target),
         {
             "sessions": projections,
-            "page": {
-                "kind": "limit",
-                "limit": limit,
-                "returned_count": len(projections),
-                "continuation": None,
-            },
+            "page": _page(limit, SESSION_LIMIT_DEFAULT, len(projections)),
         },
         read_only=True,
     )
@@ -572,7 +613,9 @@ def get_session(dependencies: AmsDependencies, target: TenantTarget, session_id:
     with dependencies.authenticated_sdk_factory(target) as sdk:
         session = _sessions(sdk).get(session_id)
     if session is None:
-        raise SessionReadRefused("validation", "Session/tenant identity mismatch; stopped.")
+        # A 200 with a JSON null body is the server saying "no such session
+        # here" — not an identity mismatch.
+        raise SessionReadRefused("not_found", f"Session '{session_id}' was not found in this tenant.")
     _identity(session, target, session_id)
     return succeeded(
         "sessions.get", _target(target, session_id), {"session": session_projection(session)}, read_only=True
@@ -622,20 +665,33 @@ def _message_conflict(error: BaseException, session_id: str) -> SessionWriteRefu
         return None
     return SessionWriteRefused(
         "conflict",
-        f"The message was refused for session '{session_id}': the server reported a conflict. A "
-        "message's mode must match its session's mode; read the session with `hc ams sessions get` "
-        "before retrying. No message was added.",
+        f"The message was refused for session '{session_id}': the server reported a conflict — for "
+        "example, a message's mode not matching its session's mode. Read the session with "
+        "`hc ams sessions get` before retrying. No message was added.",
     )
 
 
 def _not_implemented(error: BaseException, *, session: bool) -> SessionWriteRefused | None:
+    """A 501 is the server saying it does not serve this write yet.
+
+    Both routes report the 501 the server actually sent rather than asserting
+    the requested mode was the cause; implement mode is named as the documented
+    reason, not as a certainty.
+    """
+
     if getattr(error, "status_code", None) != 501:
         return None
-    what = "Sessions in" if session else "Messages in"
+    if session:
+        return SessionWriteRefused(
+            "unsupported",
+            "The server does not serve this session write yet (it answered 501, not implemented); the "
+            "write was refused and no changes were made. Implement mode is the documented reason: "
+            "implement-mode authoring is not available from this server yet.",
+        )
     return SessionWriteRefused(
         "unsupported",
-        f"{what} implement mode are not available from this server yet; the write was refused and "
-        "no changes were made.",
+        "The server does not serve this message write yet (it answered 501, not implemented); no "
+        "message was added. Implement-mode messages are not available from this server yet.",
     )
 
 
@@ -709,7 +765,7 @@ def list_messages(
     limit = _limit(limit, MESSAGE_LIMIT_MAX, "--limit")
     with dependencies.authenticated_sdk_factory(target) as sdk:
         try:
-            messages = _messages(sdk).list(session_id, **({} if limit is None else {"limit": limit}))
+            messages = _messages(sdk, ("list",)).list(session_id, **({} if limit is None else {"limit": limit}))
         except HealthCloudHTTPError as error:
             if getattr(error, "status_code", None) == 404:
                 raise SessionReadRefused(
@@ -724,12 +780,7 @@ def list_messages(
         _target(target, session_id),
         {
             "messages": projections,
-            "page": {
-                "kind": "limit",
-                "limit": limit,
-                "returned_count": len(projections),
-                "continuation": None,
-            },
+            "page": _page(limit, MESSAGE_LIMIT_DEFAULT, len(projections)),
         },
         read_only=True,
     )
@@ -944,6 +995,7 @@ def generate_plan(
     session_id = _session_id(session_id)
     operation = _plan_operation(operation)
     prompt = None if prompt_file is None else _prompt_file(prompt_file)
+    idempotency_key = _idempotency_key(idempotency_key, PlanReviewRefused)
     with private_output(out) as write, dependencies.authenticated_sdk_factory(target) as sdk:
         resource = _plans(sdk, ("generate",), write=True)
         try:
@@ -1038,6 +1090,7 @@ def add_message(
         refuse=SessionWriteRefused,
         required=True,
     )
+    idempotency_key = _idempotency_key(idempotency_key, SessionWriteRefused)
     with dependencies.authenticated_sdk_factory(target) as sdk:
         resource = _messages(sdk, ("add",), write=True)
         try:
@@ -1067,8 +1120,13 @@ def add_message(
             "anything else.",
         )
     data: dict = {"message": message_projection(message)}
-    if idempotency_key is not None:
-        data["idempotency_key"] = idempotency_key
+    # Echo the server's readback key when the message carries one, so the
+    # envelope never asserts a key→message association the server did not
+    # confirm. When the readback omits the key entirely the field is omitted
+    # too — the caller can see the key they passed in their own command line.
+    readback_key = getattr(message, "idempotency_key", None)
+    if readback_key is not None:
+        data["idempotency_key"] = readback_key
     return succeeded("sessions.messages.add", _target(target, session_id), data, read_only=False)
 
 

{healthcloud_cli-3.7.5 → healthcloud_cli-3.7.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "healthcloud-cli"
-version = "3.7.5"
+version = "3.7.7"
 description = "Command-line interface for the HealthCloud MCP gateway, generated from the shared MCP tool manifest."
 readme = "README.md"
 requires-python = ">=3.14"