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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: healthcloud-cli
-Version: 3.7.5
+Version: 3.7.6
 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
@@ -1099,8 +1099,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
@@ -1131,16 +1135,18 @@ uv run --frozen hc ams sessions messages add --environment dev --tenant-id TENAN
 - `--mode implement` is not available from the server yet: `create` reports one
   `unsupported` refusal (the server answers 501) and creates nothing. 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 +1155,10 @@ 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, and `messages add` still refuses `unsupported`
+  without it. 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 +1249,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.6}/README.md

@@ -1081,8 +1081,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
@@ -1113,16 +1117,18 @@ uv run --frozen hc ams sessions messages add --environment dev --tenant-id TENAN
 - `--mode implement` is not available from the server yet: `create` reports one
   `unsupported` refusal (the server answers 501) and creates nothing. 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 +1137,10 @@ 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, and `messages add` still refuses `unsupported`
+  without it. 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 +1231,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.6}/healthcloud_cli/ams/sessions/operations.py

@@ -87,6 +87,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
@@ -572,7 +594,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,9 +646,9 @@ 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.",
     )
 
 
@@ -709,7 +733,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(
@@ -944,6 +968,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 +1063,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 +1093,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.6}/pyproject.toml

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