healthcloud-cli 3.4.0__tar.gz → 3.5.0__tar.gz

{healthcloud_cli-3.4.0 → healthcloud_cli-3.5.0}/.gitignore

@@ -255,3 +255,8 @@ packages/pip-tenantadmin/README.md
 
 # Live SDK test assets stay in the archived SDK history, outside this source import.
 integration-tests/shared/test-assets/
+
+# Ralph loop runtime state
+.ralph/
+/PROMPT.md
+.blind-peer-review/

{healthcloud_cli-3.4.0 → healthcloud_cli-3.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: healthcloud-cli
-Version: 3.4.0
+Version: 3.5.0
 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
@@ -293,6 +293,31 @@ uv run --frozen hc logout
 otherwise it prompts (with hidden password input). It stores only the email,
 tenant/environment binding, access/refresh tokens and expiry in the strict
 owner-only `~/.healthcloud/cli/ams-session.json`; it never stores the password.
+
+For CI and agents, log in non-interactively: pass `--email` and pipe the password
+to `--password-stdin` (read as exactly one stdin line, never echoed, never a
+flag value — there is no `--password` option):
+
+```bash
+printf '%s\n' "$HC_AMS_ADMIN_PASSWORD" | \
+  uv run --frozen hc login --environment dev --tenant-id TENANT_ID \
+  --email "$HC_AMS_ADMIN_EMAIL" --password-stdin
+```
+
+`--email` beats `HC_AMS_ADMIN_EMAIL` and `--password-stdin` beats
+`HC_AMS_ADMIN_PASSWORD`. With `--password-stdin`, the piped line is always the
+password: it is read before any prompt, so it can never be consumed as the
+email, and the email must come from `--email`, `HC_AMS_ADMIN_EMAIL` or (only on
+an interactive terminal) the email prompt. When stdin is not an interactive
+terminal and neither `--password-stdin` nor `HC_AMS_ADMIN_PASSWORD` supplies the
+password, `hc login` refuses with that guidance instead of attempting a hidden
+prompt (no `GetPassWarning`, no echoed password); a missing email on a
+non-interactive stdin (or a process with no stdin stream at all) is refused the
+same way, naming `--email`/`--password-stdin`; every refusal happens before any
+login request. `--status` cannot be combined with `--email` or `--password-stdin`.
+Even on an interactive terminal, `--password-stdin` suppresses terminal echo
+while the single line is read and restores it afterwards; a stdin stream that is
+closed or errors mid-read is refused cleanly (exit 2, never a traceback).
 AMS commands may omit both target flags while this session is present, except
 that a `prod` session still needs `--environment prod` on every command. Explicit
 flags and target files must match it exactly. A session within 60 seconds of
@@ -320,11 +345,22 @@ uv run --frozen hc ams discover --environment dev --tenant-id TENANT_ID
 Read-only agent listing, inspection and export take flags instead of a target
 file; both may be omitted together when a matching saved session exists. Without
 one, they log in as tenant admin using `HC_AMS_ADMIN_EMAIL` /
-`HC_AMS_ADMIN_PASSWORD`. Stdout carries bounded metadata only; `adapter` shows
+`HC_AMS_ADMIN_PASSWORD`. They emit the same versioned result envelope as the
+other read domains (`operation`, `outcome`, `schema_version`, `target`, `data`;
+no `verification` block on reads); failures emit one categorized JSON error
+envelope on stderr with the same categories (not found, target mismatch,
+refusal, logged out), not the plain-text `Error: …` lines of earlier releases.
+`agents list` carries bounded projections under `data.agents` plus a `page`
+block; `agents get` carries the bounded projection under `data.agent`. The
+legacy top-level `{"agents": …, "environment": …, "tenant_id": …}` shape is
+intentionally replaced by this envelope — scripts must read the new shape.
+Stdout carries bounded metadata only; `adapter` shows
 whether an agent runs from the `file` or `db` config adapter (`unknown` when the
 server does not say). `export` first re-checks the agent/tenant identity, then
 saves the server's own JSON/YAML export byte-for-byte to a new owner-only `--out`
-file, refusing (and leaving no file) when the body is not valid UTF-8. `export`
+file (exact bytes preserved), refusing (and leaving no file) when the body is
+not valid UTF-8; its stdout reports the envelope with the file `path`, `format`
+and `sha256` under `data` and the `agent_id` in `target`. `export`
 needs an AMS build that serves `/agents/{agent_id}/configuration/export`; that
 route is not yet deployed to dev:
 
@@ -335,6 +371,23 @@ uv run --frozen hc ams agents export --environment dev --tenant-id TENANT_ID --a
   --format yaml --out agent.yaml
 ```
 
+For example, `hc ams agents list` succeeds with (formatted for readability):
+
+```json
+{"schema_version": 1, "operation": "agents.list", "outcome": "succeeded",
+ "target": {"environment": "dev", "tenant_id": "TENANT_ID"},
+ "data": {"agents": [{"id": "AGENT_ID", "name": "…", "adapter": "file", "…": "…"}],
+          "page": {"kind": "unpaged", "returned_count": 1, "continuation": null}}}
+```
+
+and a missing `--agent-id` fails with one envelope on stderr and exit 1:
+
+```json
+{"schema_version": 1, "operation": "agents.get", "outcome": "failed",
+ "target": {"environment": "dev", "tenant_id": "TENANT_ID", "agent_id": "AGENT_ID"},
+ "error": {"category": "not_found", "message": "Agent 'AGENT_ID' was not found."}}
+```
+
 Read-only department listing and inspection use the same explicit tenant-admin
 targeting. They emit one versioned JSON result on stdout; failures emit one
 categorized JSON result on stderr. Department descriptions, creator identities,
@@ -421,6 +474,107 @@ additional data. Guardrail reads refuse target files, root credentials or base
 URLs, raw output, blank or dot-segment guardrail IDs, and installed SDKs without
 both guardrail methods before tenant-admin login or catalog reads.
 
+Read-only tool catalog listing and inspection are complete and unpaged. The
+bounded projection includes only IDs, names, read-only and confirmation flags,
+agent types, required scopes, audit events, and activity labels:
+
+```bash
+uv run --frozen hc ams tools list --environment dev --tenant-id TENANT_ID
+uv run --frozen hc ams tools get --environment dev --tenant-id TENANT_ID \
+  --tool-id TOOL_ID
+```
+
+When both target flags are omitted, these commands may use the matching saved
+tenant-admin session. Explicit flags must match that session. Tool output never
+includes descriptions, parameters, input schemas, PIP or connector routing, or
+arbitrary response fields. The CLI does not execute, assign, create, update, or
+delete tools; join agents or skills; or claim assignment, availability,
+authorization, deployment, serving, or runtime effectiveness. It makes exactly
+one catalog GET after tenant-admin login and does not paginate, retry, cache,
+join, or infer additional data. Tool reads refuse target files, root credentials
+or base URLs, raw output, blank or dot-segment IDs, and installed SDKs without
+both tool methods before tenant-admin login or catalog reads.
+
+Read-only data-source catalog listing and inspection are complete and unpaged.
+The bounded projection includes only stable IDs and names:
+
+```bash
+uv run --frozen hc ams data-sources list --environment dev --tenant-id TENANT_ID
+uv run --frozen hc ams data-sources get --environment dev --tenant-id TENANT_ID \
+  --data-source-id DATA_SOURCE_ID
+```
+
+When both target flags are omitted, these commands may use the matching saved
+tenant-admin session. Explicit flags must match that session. Data-source output
+never includes descriptions or arbitrary response fields and does not imply
+access, patient consent, record availability, assignment, authorization, or
+runtime effectiveness. The CLI does not create, update, delete, assign, access
+records through, or execute data sources. It makes exactly one catalog GET after
+tenant-admin login and does not paginate, retry, cache, truncate, join, or infer
+additional data. Data-source reads refuse target files, root credentials or base
+URLs, raw output, blank or dot-segment IDs, and installed SDKs without both
+data-source methods before tenant-admin login or catalog reads.
+
+### AMS output modes
+
+The read commands (`hc ams skills|tools|policies|guardrails|data-sources|teams|departments list|get`
+and `hc ams organization hierarchy`) render in two modes (`--output` on the root
+`hc` command; `pretty` is the default):
+
+- **`pretty`** (default): a compact human view. Lists print an `ID`/`NAME`
+  table with an entry count; a single record prints `key: value` lines; the
+  organization hierarchy prints an indented tree. Each failed AMS command
+  prints one stderr line, `error: <message> (<category>)` (flag/argument
+  usage errors from Click print Click's standard usage message instead).
+- **`json`**: the stable result envelope (below) on stdout. When stdout is not
+  a terminal, the envelope is printed as one compact line; on a terminal it is
+  indented. Errors keep the structured JSON envelope on stderr.
+
+The JSON envelope carries `schema_version`, `operation`, `target`, `outcome`,
+and either `data` (succeeded) or `error: {category, message}` (failed). On
+read-only operations the envelope no longer includes the `verification` block:
+every field there is `not_applicable` on a read, so it was boilerplate. If a
+future mutating operation reintroduces it, `verification` reappears only with
+non-`not_applicable` content. Everything else about the envelope — field names,
+ordering semantics, categories — is unchanged and stays parseable.
+
+`--raw`/`--output raw` stays refused for AMS (`Raw output is refused for AMS.`),
+and refusals keep the JSON error envelope on stderr.
+
+```bash
+hc ams skills list --environment dev --tenant-id TENANT_ID                 # pretty table
+hc ams skills get --environment dev --tenant-id TENANT_ID --skill-id SKILL_ID  # key: value
+hc --output json ams skills list --environment dev --tenant-id TENANT_ID   # compact envelope
+hc --output json ams skills list --environment dev --tenant-id TENANT_ID | jq .data
+```
+
+### What `hc ams` errors report
+
+In `json` and `raw` modes each failed AMS command prints one JSON object on stderr with
+an `error.category` and a message naming the real cause; in `pretty` mode the
+same message is exactly one stderr line, `error: <message> (<category>)`:
+
+- Local refusals keep their specific message and exit `1` with category
+  `validation`: `Raw output is refused for AMS.`, `AMS target does not match the
+  saved session; stopped before authentication.`, identity mismatches
+  (`Skill/tenant identity mismatch; stopped.`), and dot-segment ID refusals.
+- No saved session and no target flags: category `authentication` with
+  `Not logged in; run \`hc login --environment <env> --tenant-id <tenant>\`.`
+- A `get` whose requested ID does not exist (HTTP 404): category `not_found`
+  naming the ID, e.g. `Skill 'nosuch' was not found.` (a 404 on `list` stays
+  `validation`; departments keeps its legacy contract for all read statuses).
+- HTTP 401/403 map to `authentication`/`authorization`; 409 to `conflict`;
+  network failures to `transport`; local output failures to `local_io`.
+- Any unexpected internal error is category `internal` with a generic message;
+  it is never labeled `validation` and never leaks exception details.
+
+```bash
+hc --raw ams skills list --environment dev --tenant-id TENANT_ID   # validation: raw refused
+hc ams skills list --tenant-id OTHER_TENANT                        # validation: target mismatch
+hc ams skills list                                                 # authentication: not logged in
+hc ams skills get --skill-id NOSUCH                                # not_found: names the ID
+```
+
 Every other command requires an explicit local, non-secret target JSON file.
 Only the canonical HTTPS AMS origin for that environment is accepted; custom
 origins require separately verified support. Target and nested qualification keys

{healthcloud_cli-3.4.0 → healthcloud_cli-3.5.0}/README.md

@@ -275,6 +275,31 @@ uv run --frozen hc logout
 otherwise it prompts (with hidden password input). It stores only the email,
 tenant/environment binding, access/refresh tokens and expiry in the strict
 owner-only `~/.healthcloud/cli/ams-session.json`; it never stores the password.
+
+For CI and agents, log in non-interactively: pass `--email` and pipe the password
+to `--password-stdin` (read as exactly one stdin line, never echoed, never a
+flag value — there is no `--password` option):
+
+```bash
+printf '%s\n' "$HC_AMS_ADMIN_PASSWORD" | \
+  uv run --frozen hc login --environment dev --tenant-id TENANT_ID \
+  --email "$HC_AMS_ADMIN_EMAIL" --password-stdin
+```
+
+`--email` beats `HC_AMS_ADMIN_EMAIL` and `--password-stdin` beats
+`HC_AMS_ADMIN_PASSWORD`. With `--password-stdin`, the piped line is always the
+password: it is read before any prompt, so it can never be consumed as the
+email, and the email must come from `--email`, `HC_AMS_ADMIN_EMAIL` or (only on
+an interactive terminal) the email prompt. When stdin is not an interactive
+terminal and neither `--password-stdin` nor `HC_AMS_ADMIN_PASSWORD` supplies the
+password, `hc login` refuses with that guidance instead of attempting a hidden
+prompt (no `GetPassWarning`, no echoed password); a missing email on a
+non-interactive stdin (or a process with no stdin stream at all) is refused the
+same way, naming `--email`/`--password-stdin`; every refusal happens before any
+login request. `--status` cannot be combined with `--email` or `--password-stdin`.
+Even on an interactive terminal, `--password-stdin` suppresses terminal echo
+while the single line is read and restores it afterwards; a stdin stream that is
+closed or errors mid-read is refused cleanly (exit 2, never a traceback).
 AMS commands may omit both target flags while this session is present, except
 that a `prod` session still needs `--environment prod` on every command. Explicit
 flags and target files must match it exactly. A session within 60 seconds of
@@ -302,11 +327,22 @@ uv run --frozen hc ams discover --environment dev --tenant-id TENANT_ID
 Read-only agent listing, inspection and export take flags instead of a target
 file; both may be omitted together when a matching saved session exists. Without
 one, they log in as tenant admin using `HC_AMS_ADMIN_EMAIL` /
-`HC_AMS_ADMIN_PASSWORD`. Stdout carries bounded metadata only; `adapter` shows
+`HC_AMS_ADMIN_PASSWORD`. They emit the same versioned result envelope as the
+other read domains (`operation`, `outcome`, `schema_version`, `target`, `data`;
+no `verification` block on reads); failures emit one categorized JSON error
+envelope on stderr with the same categories (not found, target mismatch,
+refusal, logged out), not the plain-text `Error: …` lines of earlier releases.
+`agents list` carries bounded projections under `data.agents` plus a `page`
+block; `agents get` carries the bounded projection under `data.agent`. The
+legacy top-level `{"agents": …, "environment": …, "tenant_id": …}` shape is
+intentionally replaced by this envelope — scripts must read the new shape.
+Stdout carries bounded metadata only; `adapter` shows
 whether an agent runs from the `file` or `db` config adapter (`unknown` when the
 server does not say). `export` first re-checks the agent/tenant identity, then
 saves the server's own JSON/YAML export byte-for-byte to a new owner-only `--out`
-file, refusing (and leaving no file) when the body is not valid UTF-8. `export`
+file (exact bytes preserved), refusing (and leaving no file) when the body is
+not valid UTF-8; its stdout reports the envelope with the file `path`, `format`
+and `sha256` under `data` and the `agent_id` in `target`. `export`
 needs an AMS build that serves `/agents/{agent_id}/configuration/export`; that
 route is not yet deployed to dev:
 
@@ -317,6 +353,23 @@ uv run --frozen hc ams agents export --environment dev --tenant-id TENANT_ID --a
   --format yaml --out agent.yaml
 ```
 
+For example, `hc ams agents list` succeeds with (formatted for readability):
+
+```json
+{"schema_version": 1, "operation": "agents.list", "outcome": "succeeded",
+ "target": {"environment": "dev", "tenant_id": "TENANT_ID"},
+ "data": {"agents": [{"id": "AGENT_ID", "name": "…", "adapter": "file", "…": "…"}],
+          "page": {"kind": "unpaged", "returned_count": 1, "continuation": null}}}
+```
+
+and a missing `--agent-id` fails with one envelope on stderr and exit 1:
+
+```json
+{"schema_version": 1, "operation": "agents.get", "outcome": "failed",
+ "target": {"environment": "dev", "tenant_id": "TENANT_ID", "agent_id": "AGENT_ID"},
+ "error": {"category": "not_found", "message": "Agent 'AGENT_ID' was not found."}}
+```
+
 Read-only department listing and inspection use the same explicit tenant-admin
 targeting. They emit one versioned JSON result on stdout; failures emit one
 categorized JSON result on stderr. Department descriptions, creator identities,
@@ -403,6 +456,107 @@ additional data. Guardrail reads refuse target files, root credentials or base
 URLs, raw output, blank or dot-segment guardrail IDs, and installed SDKs without
 both guardrail methods before tenant-admin login or catalog reads.
 
+Read-only tool catalog listing and inspection are complete and unpaged. The
+bounded projection includes only IDs, names, read-only and confirmation flags,
+agent types, required scopes, audit events, and activity labels:
+
+```bash
+uv run --frozen hc ams tools list --environment dev --tenant-id TENANT_ID
+uv run --frozen hc ams tools get --environment dev --tenant-id TENANT_ID \
+  --tool-id TOOL_ID
+```
+
+When both target flags are omitted, these commands may use the matching saved
+tenant-admin session. Explicit flags must match that session. Tool output never
+includes descriptions, parameters, input schemas, PIP or connector routing, or
+arbitrary response fields. The CLI does not execute, assign, create, update, or
+delete tools; join agents or skills; or claim assignment, availability,
+authorization, deployment, serving, or runtime effectiveness. It makes exactly
+one catalog GET after tenant-admin login and does not paginate, retry, cache,
+join, or infer additional data. Tool reads refuse target files, root credentials
+or base URLs, raw output, blank or dot-segment IDs, and installed SDKs without
+both tool methods before tenant-admin login or catalog reads.
+
+Read-only data-source catalog listing and inspection are complete and unpaged.
+The bounded projection includes only stable IDs and names:
+
+```bash
+uv run --frozen hc ams data-sources list --environment dev --tenant-id TENANT_ID
+uv run --frozen hc ams data-sources get --environment dev --tenant-id TENANT_ID \
+  --data-source-id DATA_SOURCE_ID
+```
+
+When both target flags are omitted, these commands may use the matching saved
+tenant-admin session. Explicit flags must match that session. Data-source output
+never includes descriptions or arbitrary response fields and does not imply
+access, patient consent, record availability, assignment, authorization, or
+runtime effectiveness. The CLI does not create, update, delete, assign, access
+records through, or execute data sources. It makes exactly one catalog GET after
+tenant-admin login and does not paginate, retry, cache, truncate, join, or infer
+additional data. Data-source reads refuse target files, root credentials or base
+URLs, raw output, blank or dot-segment IDs, and installed SDKs without both
+data-source methods before tenant-admin login or catalog reads.
+
+### AMS output modes
+
+The read commands (`hc ams skills|tools|policies|guardrails|data-sources|teams|departments list|get`
+and `hc ams organization hierarchy`) render in two modes (`--output` on the root
+`hc` command; `pretty` is the default):
+
+- **`pretty`** (default): a compact human view. Lists print an `ID`/`NAME`
+  table with an entry count; a single record prints `key: value` lines; the
+  organization hierarchy prints an indented tree. Each failed AMS command
+  prints one stderr line, `error: <message> (<category>)` (flag/argument
+  usage errors from Click print Click's standard usage message instead).
+- **`json`**: the stable result envelope (below) on stdout. When stdout is not
+  a terminal, the envelope is printed as one compact line; on a terminal it is
+  indented. Errors keep the structured JSON envelope on stderr.
+
+The JSON envelope carries `schema_version`, `operation`, `target`, `outcome`,
+and either `data` (succeeded) or `error: {category, message}` (failed). On
+read-only operations the envelope no longer includes the `verification` block:
+every field there is `not_applicable` on a read, so it was boilerplate. If a
+future mutating operation reintroduces it, `verification` reappears only with
+non-`not_applicable` content. Everything else about the envelope — field names,
+ordering semantics, categories — is unchanged and stays parseable.
+
+`--raw`/`--output raw` stays refused for AMS (`Raw output is refused for AMS.`),
+and refusals keep the JSON error envelope on stderr.
+
+```bash
+hc ams skills list --environment dev --tenant-id TENANT_ID                 # pretty table
+hc ams skills get --environment dev --tenant-id TENANT_ID --skill-id SKILL_ID  # key: value
+hc --output json ams skills list --environment dev --tenant-id TENANT_ID   # compact envelope
+hc --output json ams skills list --environment dev --tenant-id TENANT_ID | jq .data
+```
+
+### What `hc ams` errors report
+
+In `json` and `raw` modes each failed AMS command prints one JSON object on stderr with
+an `error.category` and a message naming the real cause; in `pretty` mode the
+same message is exactly one stderr line, `error: <message> (<category>)`:
+
+- Local refusals keep their specific message and exit `1` with category
+  `validation`: `Raw output is refused for AMS.`, `AMS target does not match the
+  saved session; stopped before authentication.`, identity mismatches
+  (`Skill/tenant identity mismatch; stopped.`), and dot-segment ID refusals.
+- No saved session and no target flags: category `authentication` with
+  `Not logged in; run \`hc login --environment <env> --tenant-id <tenant>\`.`
+- A `get` whose requested ID does not exist (HTTP 404): category `not_found`
+  naming the ID, e.g. `Skill 'nosuch' was not found.` (a 404 on `list` stays
+  `validation`; departments keeps its legacy contract for all read statuses).
+- HTTP 401/403 map to `authentication`/`authorization`; 409 to `conflict`;
+  network failures to `transport`; local output failures to `local_io`.
+- Any unexpected internal error is category `internal` with a generic message;
+  it is never labeled `validation` and never leaks exception details.
+
+```bash
+hc --raw ams skills list --environment dev --tenant-id TENANT_ID   # validation: raw refused
+hc ams skills list --tenant-id OTHER_TENANT                        # validation: target mismatch
+hc ams skills list                                                 # authentication: not logged in
+hc ams skills get --skill-id NOSUCH                                # not_found: names the ID
+```
+
 Every other command requires an explicit local, non-secret target JSON file.
 Only the canonical HTTPS AMS origin for that environment is accepted; custom
 origins require separately verified support. Target and nested qualification keys

{healthcloud_cli-3.4.0 → healthcloud_cli-3.5.0}/healthcloud_cli/ams/agents/commands.py

@@ -6,11 +6,10 @@ from pathlib import Path
 
 import click
 
-from ..compatibility import safe_errors
 from ..context import AmsDependencies, pass_ams, preflight_agents
-from ..output import metadata
+from ..errors import run_domain
 from ..session import resolve_tenant_target
-from .operations import AgentReadRefused, export_agent, get_agent, list_agents
+from .operations import export_agent, get_agent, list_agents
 
 
 def _environment(function):
@@ -25,22 +24,21 @@ def _agent(function):
     return click.option("--agent-id", required=True)(function)
 
 
-def _run(operation, *args):
-    try:
-        return operation(*args)
-    except AgentReadRefused as exc:
-        raise click.ClickException(str(exc)) from None
-
-
 def create_list_command(dependencies: AmsDependencies) -> click.Command:
     @click.command("list")
     @_environment
     @_tenant
     @pass_ams
-    @safe_errors
     def command(invocation, environment: str | None, tenant_id: str | None) -> None:
-        preflight_agents(invocation)
-        metadata(_run(list_agents, dependencies, resolve_tenant_target(environment, tenant_id)))
+        target_data = {"environment": environment, "tenant_id": tenant_id}
+
+        def execute():
+            target = resolve_tenant_target(environment, tenant_id)
+            target_data.update(environment=target.environment, tenant_id=target.tenant_id)
+            preflight_agents(invocation)
+            return list_agents(dependencies, target)
+
+        run_domain("agents.list", target_data, execute)
 
     return command
 
@@ -51,10 +49,16 @@ def create_get_command(dependencies: AmsDependencies) -> click.Command:
     @_tenant
     @_agent
     @pass_ams
-    @safe_errors
     def command(invocation, environment: str | None, tenant_id: str | None, agent_id: str) -> None:
-        preflight_agents(invocation)
-        metadata(_run(get_agent, dependencies, resolve_tenant_target(environment, tenant_id), agent_id))
+        target_data = {"environment": environment, "tenant_id": tenant_id, "agent_id": agent_id}
+
+        def execute():
+            target = resolve_tenant_target(environment, tenant_id)
+            target_data.update(environment=target.environment, tenant_id=target.tenant_id)
+            preflight_agents(invocation)
+            return get_agent(dependencies, target, agent_id)
+
+        run_domain("agents.get", target_data, execute)
 
     return command
 
@@ -67,7 +71,6 @@ def create_export_command(dependencies: AmsDependencies) -> click.Command:
     @click.option("--out", required=True, type=click.Path(path_type=Path, dir_okay=False))
     @click.option("--format", "export_format", type=click.Choice(["json", "yaml"]), default="json", show_default=True)
     @pass_ams
-    @safe_errors
     def command(
         invocation,
         environment: str | None,
@@ -76,8 +79,14 @@ def create_export_command(dependencies: AmsDependencies) -> click.Command:
         out: Path,
         export_format: str,
     ) -> None:
-        preflight_agents(invocation)
-        target = resolve_tenant_target(environment, tenant_id)
-        metadata(_run(export_agent, dependencies, target, agent_id, out, export_format))
+        target_data = {"environment": environment, "tenant_id": tenant_id, "agent_id": agent_id}
+
+        def execute():
+            target = resolve_tenant_target(environment, tenant_id)
+            target_data.update(environment=target.environment, tenant_id=target.tenant_id)
+            preflight_agents(invocation)
+            return export_agent(dependencies, target, agent_id, out, export_format)
+
+        run_domain("agents.export", target_data, execute)
 
     return command

{healthcloud_cli-3.4.0 → healthcloud_cli-3.5.0}/healthcloud_cli/ams/agents/operations.py

@@ -7,18 +7,29 @@ from pathlib import Path
 from typing import Literal
 
 from ..context import AmsDependencies
+from ..domain_errors import DomainReadRefused
 from ..output import private_text_output
+from ..results import succeeded
 from ..target import TenantTarget
 from .projections import detail, summary
 
 
-class AgentReadRefused(ValueError):
-    """A stable refusal safe for the CLI adapter to expose."""
+class AgentReadRefused(DomainReadRefused):
+    """A categorized agent refusal safe for the CLI adapter to expose."""
+
+    pass
 
 
 def _agent_id(value: str) -> str:
     if not isinstance(value, str) or not value.strip():
-        raise AgentReadRefused("Explicit agent ID required.")
+        raise AgentReadRefused("validation", "Explicit agent ID required.")
+    return value
+
+
+def _target(target: TenantTarget, agent_id: str | None = None) -> dict:
+    value = {"environment": target.environment, "tenant_id": target.tenant_id}
+    if agent_id is not None:
+        value["agent_id"] = agent_id
     return value
 
 
@@ -26,18 +37,23 @@ def list_agents(dependencies: AmsDependencies, target: TenantTarget) -> dict:
     with dependencies.authenticated_sdk_factory(target) as sdk:
         agents = sdk.ams_admin.list_agents()
     if any(agent.tenant_id != target.tenant_id for agent in agents):
-        raise AgentReadRefused("Agent/tenant identity mismatch; stopped.")
-    return {
-        "environment": target.environment,
-        "tenant_id": target.tenant_id,
-        "agents": [summary(agent) for agent in agents],
-    }
+        raise AgentReadRefused("validation", "Agent/tenant identity mismatch; stopped.")
+    projections = [summary(agent) for agent in agents]
+    return succeeded(
+        "agents.list",
+        _target(target),
+        {
+            "agents": projections,
+            "page": {"kind": "unpaged", "returned_count": len(projections), "continuation": None},
+        },
+        read_only=True,
+    )
 
 
 def _verified_agent(sdk, target: TenantTarget, agent_id: str):
     agent = sdk.ams_admin.get_agent(agent_id)
     if agent is None or agent.id != agent_id or agent.tenant_id != target.tenant_id:
-        raise AgentReadRefused("Agent/tenant identity mismatch; stopped.")
+        raise AgentReadRefused("validation", "Agent/tenant identity mismatch; stopped.")
     return agent
 
 
@@ -45,7 +61,12 @@ def get_agent(dependencies: AmsDependencies, target: TenantTarget, agent_id: str
     agent_id = _agent_id(agent_id)
     with dependencies.authenticated_sdk_factory(target) as sdk:
         agent = _verified_agent(sdk, target, agent_id)
-    return {"environment": target.environment, "tenant_id": target.tenant_id} | detail(agent)
+    return succeeded(
+        "agents.get",
+        _target(target, agent_id),
+        {"agent": detail(agent)},
+        read_only=True,
+    )
 
 
 def export_agent(
@@ -57,16 +78,18 @@ def export_agent(
 ) -> dict:
     agent_id = _agent_id(agent_id)
     if export_format not in ("json", "yaml"):
-        raise AgentReadRefused("Export format must be json or yaml.")
+        raise AgentReadRefused("validation", "Export format must be json or yaml.")
     with private_text_output(output) as write, dependencies.authenticated_sdk_factory(target) as sdk:
         _verified_agent(sdk, target, agent_id)
         text = sdk.ams_admin.export_agent_configuration(agent_id, format=export_format)
         write(text)
-    return {
-        "environment": target.environment,
-        "tenant_id": target.tenant_id,
-        "agent_id": agent_id,
-        "path": str(output),
-        "format": export_format,
-        "sha256": hashlib.sha256(text.encode("utf-8")).hexdigest(),
-    }
+    return succeeded(
+        "agents.export",
+        _target(target, agent_id),
+        {
+            "path": str(output),
+            "format": export_format,
+            "sha256": hashlib.sha256(text.encode("utf-8")).hexdigest(),
+        },
+        read_only=True,
+    )

{healthcloud_cli-3.4.0 → healthcloud_cli-3.5.0}/healthcloud_cli/ams/context.py

@@ -197,6 +197,48 @@ def preflight_guardrails(invocation: AmsContext, target: TenantTarget) -> None:
         sdk.close()
 
 
+def preflight_tools(invocation: AmsContext, target: TenantTarget) -> None:
+    """Validate local tool-read compatibility before login or data reads."""
+
+    _check_root(invocation)
+    if invocation.target_file is not None:
+        raise click.ClickException("Tools requires explicit environment/tenant flags, without a target file.")
+    sdk = HCSDK(environment=target.environment, tenant_id=target.tenant_id)
+    try:
+        resource = getattr(getattr(sdk, "ams_admin", None), "tools", None)
+        if (
+            resource is None
+            or not callable(getattr(resource, "list", None))
+            or not callable(getattr(resource, "get", None))
+        ):
+            raise click.ClickException(
+                "SDK missing ams_admin tools; use the reviewed SDK version required by this CLI."
+            )
+    finally:
+        sdk.close()
+
+
+def preflight_data_sources(invocation: AmsContext, target: TenantTarget) -> None:
+    """Validate local data-source-read compatibility before login or data reads."""
+
+    _check_root(invocation)
+    if invocation.target_file is not None:
+        raise click.ClickException("Data sources requires explicit environment/tenant flags, without a target file.")
+    sdk = HCSDK(environment=target.environment, tenant_id=target.tenant_id)
+    try:
+        resource = getattr(getattr(sdk, "ams_admin", None), "data_sources", None)
+        if (
+            resource is None
+            or not callable(getattr(resource, "list", None))
+            or not callable(getattr(resource, "get", None))
+        ):
+            raise click.ClickException(
+                "SDK missing ams_admin data sources; use the reviewed SDK version required by this CLI."
+            )
+    finally:
+        sdk.close()
+
+
 def require_target(invocation: AmsContext) -> AmsTarget:
     """Validate root options and load the explicitly selected AMS target."""
 

healthcloud_cli-3.5.0/healthcloud_cli/ams/data_sources/__init__.py

@@ -0,0 +1,5 @@
+"""Read-only AMS data-source CLI domain."""
+
+from .group import create_data_sources_group
+
+__all__ = ["create_data_sources_group"]