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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: healthcloud-cli
-Version: 3.7.7
+Version: 3.7.9
 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
@@ -529,14 +529,15 @@ and a missing `--agent-id` fails with one envelope on stderr and exit 1:
 ```
 
 Agent lifecycle changes are two first-class, send-once write commands. They
-require a saved `hc login` session (env-var credentials are not accepted for
-writes) and an explicit `--expected-config-version`, `--confirm` acknowledgement:
+require a saved `hc login` session (the command refuses before any request when
+none is saved; env-var credentials are not accepted here) and the `--confirm`
+acknowledgement. `--expected-config-version` is optional:
 
 ```bash
 uv run --frozen hc ams agents deactivate --environment dev --tenant-id TENANT_ID \
-  --agent-id AGENT_ID --expected-config-version N --confirm
+  --agent-id AGENT_ID [--expected-config-version N] --confirm
 uv run --frozen hc ams agents activate --environment dev --tenant-id TENANT_ID \
-  --agent-id AGENT_ID --expected-config-version N --confirm
+  --agent-id AGENT_ID [--expected-config-version N] --confirm
 ```
 
 Each command issues exactly one `GET /agents/{agent_id}`, local pre-checks,
@@ -566,9 +567,21 @@ explicitly that
 fields — a disabled agent can still be selected by those paths — and that
 in-flight runs, WSS sessions and schedules are untouched by this route.
 
+`data.config_version_check` says which concurrent-edit check actually ran:
+`matched` (the read `config_version` equals `--expected-config-version`),
+`not_run` (the flag was omitted, so **no** version check ran and the reviewed
+target plus `--confirm` are the approval), never a silent success. It is carried
+on the confirmed, refused **and** unknown envelopes alike, so an outcome where
+the write may already have committed still says which check ran. A deployment
+whose agent payload omits or nulls `config_version` cannot honour the flag: the
+command refuses that flag with a way forward (`Re-run without
+--expected-config-version`) instead of refusing every lifecycle command forever
+and instead of interpolating a Python `None` repr.
+
 Default `pretty` output prints those facts as labelled lines — `transition`,
-`requested`, `evidence` (`saved`, `side_effects`, `runtime`), `eligibility`,
-`mutation_replayed: false` — and closes with a `verification:` block, so a
+`requested`, `config_version_check`, `evidence` (`saved`, `side_effects`,
+`runtime`), `eligibility`, `mutation_replayed: false` — and closes with a
+`verification:` block, so a
 deactivate reads `transition: deactivate`, then
 `evidence: / saved: / status: confirmed`, then `verification: / saved_state:
 confirmed`, `side_effects: unverified`, `runtime: unverified`; it is never one
@@ -592,24 +605,45 @@ tenant, an already in-effect state, an unsupported `archived`/`draft` target
 (named as having no supported reversible transition here), or a
 `config_version` that no longer matches `--expected-config-version` — all of
 these are also enforced by the preview, which still sends nothing. A missing
-`--confirm` exits 2. That version check is a local best-effort
+`--confirm` exits 2. An `active` value the server emits as `1`/`0`/`"true"`/
+`"false"` is interpreted as a flag (an already in-effect state is still
+recognised and a correct write is still confirmed); any other value is
+unconfirmed, never a false success. That version check is a local best-effort
 guard only: the route has no `If-Match` and the server never compares the
 version, so it cannot prove atomicity and a request could still race between
 the read and the PUT.
 
-A transport error or `5xx` from the PUT is reported as `outcome: "unknown"`
-with `mutation_replayed: false`, `verification.saved_state: "unknown"` and a
+A transport error, a `5xx`/`408` from the PUT, or an interrupt (`Ctrl-C`) during
+the PUT or the readback is reported as `outcome: "unknown"` with
+`mutation_replayed: false`, `verification.saved_state: "unknown"` and a
 `reconciliation: {"status": "not_read", …}` block; the CLI sends no retry and
 does not re-read automatically — run `hc ams agents get` before doing anything
 else. A failed readback after an accepted PUT is reported the same way (unknown,
 not success). A `2xx` PUT answer whose body cannot be read as an agent object is
-also `outcome: "unknown"` (sent once, saved state unverified), never an internal
-error and never a success.
+also `outcome: "unknown"` (attempted once; the request may not have been sent
+and its saved state is unverified), never an internal error and never a
+success.
+
+A non-`5xx` rejection of the PUT (`409`, `422`, `400`, `403`, …) is worded as a
+**write** that the server refused, never as a read: `outcome: "failed"`,
+`verification.saved_state: "failed"`, `mutation_replayed: false`, the pre-write
+state under `data.evidence.saved.before`, and a `reconciliation` saying the CLI
+did not re-read. A `2xx` body that is not an agent object at all (for example a
+plain-text body) is a bounded `validation` refusal with the same
+`verification: not_applicable` as any read, never an `AttributeError` and never a
+traceback.
+
+The saved-session requirement above is enforced at the command boundary: the
+shared AMS authentication path still has the `HC_AMS_ADMIN_EMAIL`/
+`HC_AMS_ADMIN_PASSWORD` tenant-admin fallback that every AMS command group uses,
+so the guarantee is "these commands refuse without a saved session", not "no AMS
+write anywhere can reach the server on env-var credentials".
 
 Capability and organization assignments are one first-class, send-once write
-command. It requires a saved `hc login` session (env-var credentials are not
-accepted for writes), an explicit `--expected-config-version`, and the
-`--confirm` acknowledgement of the target and the printed reviewed diff:
+command. It requires a saved `hc login` session (the command refuses before any
+request when none is saved; env-var credentials are not accepted here), an
+explicit `--expected-config-version`, and the `--confirm` acknowledgement of the
+target and the printed reviewed diff:
 
 ```bash
 uv run --frozen hc ams agents assignments set --environment dev --tenant-id TENANT_ID \
@@ -706,8 +740,9 @@ carries a reference field is refused by field name by
 capabilities.
 
 Deleting an agent is one first-class, send-once destructive command. It requires
-a saved `hc login` session (env-var credentials are not accepted for writes) and
-the `--confirm` acknowledgement of the target and disclosure block it prints:
+a saved `hc login` session (the command refuses before any request when none is
+saved; env-var credentials are not accepted here) and the `--confirm`
+acknowledgement of the target and disclosure block it prints:
 
 ```bash
 uv run --frozen hc ams agents delete --environment dev --tenant-id TENANT_ID \
@@ -1269,7 +1304,12 @@ uv run --frozen hc ams sessions plans reconcile --environment dev --tenant-id TE
   `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
-  read and needs no saved `hc login` session.
+  read and needs no saved `hc login` session: it authenticates like every other
+  session read, with the saved session when there is one and otherwise with the
+  environment's own `HC_AMS_ADMIN_EMAIL`/`HC_AMS_ADMIN_PASSWORD` credentials.
+  A refusal is worded for the operation that was refused, so a `422` or `503`
+  on `get` never claims a plan "was generated": `generate` says no plan was
+  generated, `get` says no plan was reloaded.
 - `--out` is required and must be a new path: the review is written to a
   newly created owner-only file (mode `0600`, no symlinks, never overwritten).
   A refusal removes the reservation again, so a refused review never leaves a
@@ -1286,6 +1326,13 @@ uv run --frozen hc ams sessions plans reconcile --environment dev --tenant-id TE
   guardrail/data-source) for a creation plan. `plan_json["original_prompt"]`
   is never projected, and `warnings`/`skipped_references` are reported as
   counts, not bodies.
+- The review file marks the text a model produced: `content_origin` is
+  `"model-generated"` and `model_generated_fields` lists the fields whose values
+  came from the planner — `summary`, `changes.*.why`,
+  `definition.instructions`/`greetings`/`name`/`description`/opening suggestions
+  and `review_warnings[].message`. Those values are data to inspect before you
+  approve, never instructions to the reader or to an agent that later reads the
+  file.
 - stdout stays bounded and free-text-free: plan ID, `plan_hash`, operation,
   status, base config version, agent ID, model, sorted changed-field **names**
   (create: reference counts by kind) and finding counts. No prompt,
@@ -1299,7 +1346,14 @@ uv run --frozen hc ams sessions plans reconcile --environment dev --tenant-id TE
   `--output json` prints the full envelope, unchanged.
 - The prompt is protected free text and never comes from argv: `--prompt-file`
   reads one owner-only regular text file (no symlinks, at most 20000
-  characters) and sends it once. `--prompt-file` is optional — the server falls
+  characters) and sends it once. A file that is too large, missing, unreadable,
+  not UTF-8 text, or not an owner-only regular file is a `validation` refusal
+  naming the reason and never quoting the text. Ownership is checked differently
+  per platform: on POSIX it is the file's mode and owner; on Windows the opened
+  handle's owner and DACL must grant access to your account only, so a file that
+  inherited a grant to another principal (SYSTEM, Administrators) is refused as
+  not owner-only. Keep the prompt file in a directory only your account can read.
+  `--prompt-file` is optional — the server falls
   back to the session's initial prompt or last message — and `--agent-type`
   applies to `--operation create` only (with `modify` it is a usage error
   before login or any request). `--prompt-file` is not mirrored as a local
@@ -1320,12 +1374,22 @@ uv run --frozen hc ams sessions plans reconcile --environment dev --tenant-id TE
   values, so read it in the AMS console. Non-`advisory` review findings are
   refused the same way; advisory findings are displayed in the review file.
   A creation plan that claims an `agent_id` is refused, and no existing agent
-  ID is ever fabricated or required.
+  ID is ever fabricated or required. So is a creation plan whose proposed agent
+  carries a field outside the documented definition and reference set
+  (`name`, `description`, `type`, `model`, `preferred_model`,
+  `is_orchestrator`, `department_id`, `team_id`, `instructions`, `greetings`,
+  `opening_suggestions`, `opening_suggestions_options`, and the catalog
+  `*_ids`), or whose reference field holds anything but non-blank catalog IDs:
+  the operator never approves a definition the review did not show.
 - Server answers are preserved, not replaced: a missing, expired or other
-  user's session or plan is a `not_found` refusal naming it, a `422` from the
-  plan route is a `validation` refusal carrying the server's own bounded
-  detail, and an unavailable planner (`503`) is a `transport` refusal with no
-  file written. A dropped connection on `generate` reports one `transport`
+  user's session or plan is a `not_found` refusal naming it, and an unavailable
+  planner (`503`) is a `transport` refusal with no file written. A `422` from
+  the plan route is a `validation` refusal, but its detail is only quoted when
+  it is a known static contract message that carries no field values — the
+  documented `"a prompt is required for agent creation"`. Any other `422`
+  detail can quote protected field values, exactly like `validation_errors`
+  and blocking review findings, so it is reported by category only and you read
+  it in the AMS console. A dropped connection on `generate` reports one `transport`
   error saying the plan's outcome is unknown and points at
   `hc ams sessions messages list`/`plans get` before retrying; the request is
   never re-sent automatically.

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

@@ -511,14 +511,15 @@ and a missing `--agent-id` fails with one envelope on stderr and exit 1:
 ```
 
 Agent lifecycle changes are two first-class, send-once write commands. They
-require a saved `hc login` session (env-var credentials are not accepted for
-writes) and an explicit `--expected-config-version`, `--confirm` acknowledgement:
+require a saved `hc login` session (the command refuses before any request when
+none is saved; env-var credentials are not accepted here) and the `--confirm`
+acknowledgement. `--expected-config-version` is optional:
 
 ```bash
 uv run --frozen hc ams agents deactivate --environment dev --tenant-id TENANT_ID \
-  --agent-id AGENT_ID --expected-config-version N --confirm
+  --agent-id AGENT_ID [--expected-config-version N] --confirm
 uv run --frozen hc ams agents activate --environment dev --tenant-id TENANT_ID \
-  --agent-id AGENT_ID --expected-config-version N --confirm
+  --agent-id AGENT_ID [--expected-config-version N] --confirm
 ```
 
 Each command issues exactly one `GET /agents/{agent_id}`, local pre-checks,
@@ -548,9 +549,21 @@ explicitly that
 fields — a disabled agent can still be selected by those paths — and that
 in-flight runs, WSS sessions and schedules are untouched by this route.
 
+`data.config_version_check` says which concurrent-edit check actually ran:
+`matched` (the read `config_version` equals `--expected-config-version`),
+`not_run` (the flag was omitted, so **no** version check ran and the reviewed
+target plus `--confirm` are the approval), never a silent success. It is carried
+on the confirmed, refused **and** unknown envelopes alike, so an outcome where
+the write may already have committed still says which check ran. A deployment
+whose agent payload omits or nulls `config_version` cannot honour the flag: the
+command refuses that flag with a way forward (`Re-run without
+--expected-config-version`) instead of refusing every lifecycle command forever
+and instead of interpolating a Python `None` repr.
+
 Default `pretty` output prints those facts as labelled lines — `transition`,
-`requested`, `evidence` (`saved`, `side_effects`, `runtime`), `eligibility`,
-`mutation_replayed: false` — and closes with a `verification:` block, so a
+`requested`, `config_version_check`, `evidence` (`saved`, `side_effects`,
+`runtime`), `eligibility`, `mutation_replayed: false` — and closes with a
+`verification:` block, so a
 deactivate reads `transition: deactivate`, then
 `evidence: / saved: / status: confirmed`, then `verification: / saved_state:
 confirmed`, `side_effects: unverified`, `runtime: unverified`; it is never one
@@ -574,24 +587,45 @@ tenant, an already in-effect state, an unsupported `archived`/`draft` target
 (named as having no supported reversible transition here), or a
 `config_version` that no longer matches `--expected-config-version` — all of
 these are also enforced by the preview, which still sends nothing. A missing
-`--confirm` exits 2. That version check is a local best-effort
+`--confirm` exits 2. An `active` value the server emits as `1`/`0`/`"true"`/
+`"false"` is interpreted as a flag (an already in-effect state is still
+recognised and a correct write is still confirmed); any other value is
+unconfirmed, never a false success. That version check is a local best-effort
 guard only: the route has no `If-Match` and the server never compares the
 version, so it cannot prove atomicity and a request could still race between
 the read and the PUT.
 
-A transport error or `5xx` from the PUT is reported as `outcome: "unknown"`
-with `mutation_replayed: false`, `verification.saved_state: "unknown"` and a
+A transport error, a `5xx`/`408` from the PUT, or an interrupt (`Ctrl-C`) during
+the PUT or the readback is reported as `outcome: "unknown"` with
+`mutation_replayed: false`, `verification.saved_state: "unknown"` and a
 `reconciliation: {"status": "not_read", …}` block; the CLI sends no retry and
 does not re-read automatically — run `hc ams agents get` before doing anything
 else. A failed readback after an accepted PUT is reported the same way (unknown,
 not success). A `2xx` PUT answer whose body cannot be read as an agent object is
-also `outcome: "unknown"` (sent once, saved state unverified), never an internal
-error and never a success.
+also `outcome: "unknown"` (attempted once; the request may not have been sent
+and its saved state is unverified), never an internal error and never a
+success.
+
+A non-`5xx` rejection of the PUT (`409`, `422`, `400`, `403`, …) is worded as a
+**write** that the server refused, never as a read: `outcome: "failed"`,
+`verification.saved_state: "failed"`, `mutation_replayed: false`, the pre-write
+state under `data.evidence.saved.before`, and a `reconciliation` saying the CLI
+did not re-read. A `2xx` body that is not an agent object at all (for example a
+plain-text body) is a bounded `validation` refusal with the same
+`verification: not_applicable` as any read, never an `AttributeError` and never a
+traceback.
+
+The saved-session requirement above is enforced at the command boundary: the
+shared AMS authentication path still has the `HC_AMS_ADMIN_EMAIL`/
+`HC_AMS_ADMIN_PASSWORD` tenant-admin fallback that every AMS command group uses,
+so the guarantee is "these commands refuse without a saved session", not "no AMS
+write anywhere can reach the server on env-var credentials".
 
 Capability and organization assignments are one first-class, send-once write
-command. It requires a saved `hc login` session (env-var credentials are not
-accepted for writes), an explicit `--expected-config-version`, and the
-`--confirm` acknowledgement of the target and the printed reviewed diff:
+command. It requires a saved `hc login` session (the command refuses before any
+request when none is saved; env-var credentials are not accepted here), an
+explicit `--expected-config-version`, and the `--confirm` acknowledgement of the
+target and the printed reviewed diff:
 
 ```bash
 uv run --frozen hc ams agents assignments set --environment dev --tenant-id TENANT_ID \
@@ -688,8 +722,9 @@ carries a reference field is refused by field name by
 capabilities.
 
 Deleting an agent is one first-class, send-once destructive command. It requires
-a saved `hc login` session (env-var credentials are not accepted for writes) and
-the `--confirm` acknowledgement of the target and disclosure block it prints:
+a saved `hc login` session (the command refuses before any request when none is
+saved; env-var credentials are not accepted here) and the `--confirm`
+acknowledgement of the target and disclosure block it prints:
 
 ```bash
 uv run --frozen hc ams agents delete --environment dev --tenant-id TENANT_ID \
@@ -1251,7 +1286,12 @@ uv run --frozen hc ams sessions plans reconcile --environment dev --tenant-id TE
   `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
-  read and needs no saved `hc login` session.
+  read and needs no saved `hc login` session: it authenticates like every other
+  session read, with the saved session when there is one and otherwise with the
+  environment's own `HC_AMS_ADMIN_EMAIL`/`HC_AMS_ADMIN_PASSWORD` credentials.
+  A refusal is worded for the operation that was refused, so a `422` or `503`
+  on `get` never claims a plan "was generated": `generate` says no plan was
+  generated, `get` says no plan was reloaded.
 - `--out` is required and must be a new path: the review is written to a
   newly created owner-only file (mode `0600`, no symlinks, never overwritten).
   A refusal removes the reservation again, so a refused review never leaves a
@@ -1268,6 +1308,13 @@ uv run --frozen hc ams sessions plans reconcile --environment dev --tenant-id TE
   guardrail/data-source) for a creation plan. `plan_json["original_prompt"]`
   is never projected, and `warnings`/`skipped_references` are reported as
   counts, not bodies.
+- The review file marks the text a model produced: `content_origin` is
+  `"model-generated"` and `model_generated_fields` lists the fields whose values
+  came from the planner — `summary`, `changes.*.why`,
+  `definition.instructions`/`greetings`/`name`/`description`/opening suggestions
+  and `review_warnings[].message`. Those values are data to inspect before you
+  approve, never instructions to the reader or to an agent that later reads the
+  file.
 - stdout stays bounded and free-text-free: plan ID, `plan_hash`, operation,
   status, base config version, agent ID, model, sorted changed-field **names**
   (create: reference counts by kind) and finding counts. No prompt,
@@ -1281,7 +1328,14 @@ uv run --frozen hc ams sessions plans reconcile --environment dev --tenant-id TE
   `--output json` prints the full envelope, unchanged.
 - The prompt is protected free text and never comes from argv: `--prompt-file`
   reads one owner-only regular text file (no symlinks, at most 20000
-  characters) and sends it once. `--prompt-file` is optional — the server falls
+  characters) and sends it once. A file that is too large, missing, unreadable,
+  not UTF-8 text, or not an owner-only regular file is a `validation` refusal
+  naming the reason and never quoting the text. Ownership is checked differently
+  per platform: on POSIX it is the file's mode and owner; on Windows the opened
+  handle's owner and DACL must grant access to your account only, so a file that
+  inherited a grant to another principal (SYSTEM, Administrators) is refused as
+  not owner-only. Keep the prompt file in a directory only your account can read.
+  `--prompt-file` is optional — the server falls
   back to the session's initial prompt or last message — and `--agent-type`
   applies to `--operation create` only (with `modify` it is a usage error
   before login or any request). `--prompt-file` is not mirrored as a local
@@ -1302,12 +1356,22 @@ uv run --frozen hc ams sessions plans reconcile --environment dev --tenant-id TE
   values, so read it in the AMS console. Non-`advisory` review findings are
   refused the same way; advisory findings are displayed in the review file.
   A creation plan that claims an `agent_id` is refused, and no existing agent
-  ID is ever fabricated or required.
+  ID is ever fabricated or required. So is a creation plan whose proposed agent
+  carries a field outside the documented definition and reference set
+  (`name`, `description`, `type`, `model`, `preferred_model`,
+  `is_orchestrator`, `department_id`, `team_id`, `instructions`, `greetings`,
+  `opening_suggestions`, `opening_suggestions_options`, and the catalog
+  `*_ids`), or whose reference field holds anything but non-blank catalog IDs:
+  the operator never approves a definition the review did not show.
 - Server answers are preserved, not replaced: a missing, expired or other
-  user's session or plan is a `not_found` refusal naming it, a `422` from the
-  plan route is a `validation` refusal carrying the server's own bounded
-  detail, and an unavailable planner (`503`) is a `transport` refusal with no
-  file written. A dropped connection on `generate` reports one `transport`
+  user's session or plan is a `not_found` refusal naming it, and an unavailable
+  planner (`503`) is a `transport` refusal with no file written. A `422` from
+  the plan route is a `validation` refusal, but its detail is only quoted when
+  it is a known static contract message that carries no field values — the
+  documented `"a prompt is required for agent creation"`. Any other `422`
+  detail can quote protected field values, exactly like `validation_errors`
+  and blocking review findings, so it is reported by category only and you read
+  it in the AMS console. A dropped connection on `generate` reports one `transport`
   error saying the plan's outcome is unknown and points at
   `hc ams sessions messages list`/`plans get` before retrying; the request is
   never re-sent automatically.

{healthcloud_cli-3.7.7 → healthcloud_cli-3.7.9}/healthcloud_cli/ams/agents/commands.py

@@ -93,10 +93,11 @@ def create_lifecycle_command(dependencies: AmsDependencies, transition: str) ->
     @_agent
     @click.option(
         "--expected-config-version",
-        required=True,
         type=int,
-        help="The config_version read before the write. A local best-effort guard only: the route has no "
-        "If-Match, so it never proves atomicity.",
+        default=None,
+        help="Optional: the config_version read before the write. A local best-effort guard only, because "
+        "the route has no If-Match. Omitting it runs no version check and says so in the envelope; a "
+        "deployment that reports no config_version refuses the flag rather than the whole command.",
     )
     @click.option(
         "--confirm",
@@ -111,7 +112,7 @@ def create_lifecycle_command(dependencies: AmsDependencies, transition: str) ->
         environment: str | None,
         tenant_id: str | None,
         agent_id: str,
-        expected_config_version: int,
+        expected_config_version: int | None,
         confirm: bool,
     ) -> None:
         target_data = {