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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: healthcloud-cli
-Version: 3.2.5
+Version: 3.4.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
@@ -69,10 +69,10 @@ _HC_COMPLETE=bash_complete COMP_WORDS="hc ams inspect --o" COMP_CWORD=3 uv run -
 ```
 
 Operational validation starts only when Click invokes an AMS leaf callback.
-`discover` then validates its explicit environment and tenant arguments; the
-other leaves require `--target-file` and apply the existing root, target, and
-authentication checks described below. Deferring preflight does not relax
-those safety requirements.
+`discover`, `agents`, `departments`, `teams`, `organization`, `skills`, and `policies` then
+validate their explicit environment and tenant arguments; the remaining leaves
+require `--target-file`. All apply the root, target, and authentication checks
+described below. Deferring preflight does not relax those safety requirements.
 
 The bundled tool manifest (`healthcloud_cli/contracts/mcp-tools.manifest.json`)
 is a copy of `packages/cli/contracts/mcp-tools.manifest.json`. Re-sync it
@@ -280,13 +280,147 @@ uv sync --frozen --extra dev
 uv run --frozen hc ams --help
 ```
 
-Bootstrap candidate IDs with the public SDK discovery endpoint. Both flags are
-required; no MCP defaults, admin login, or automatic candidate selection are used:
+Create one private tenant-admin session before interactive AMS work, inspect its
+non-secret binding, and remove it when finished:
+
+```bash
+uv run --frozen hc login --environment dev --tenant-id TENANT_ID
+uv run --frozen hc login --status
+uv run --frozen hc logout
+```
+
+`hc login` reads `HC_AMS_ADMIN_EMAIL` and `HC_AMS_ADMIN_PASSWORD` when present,
+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.
+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
+expiry is refreshed once before the operation, under a lock so concurrent
+commands never spend the same refresh token (a second command waits up to 30 seconds, then stops), and
+atomically replaced. Refresh
+failure stops without an AMS call or password fallback and asks for a new login.
+If the refreshed session cannot be saved, the current command still finishes and
+prints a warning to run `hc login` again.
+
+`~/.healthcloud` and `~/.healthcloud/cli` must be directories you own with mode
+700; the CLI creates them that way, and refuses (naming the directory and the
+`chmod 700` fix) if an existing one is shared. `hc logout` deletes the local file
+only and reports `"server_session_revoked": false`: issued tokens stay valid
+until they expire.
+
+Bootstrap candidate IDs with the public SDK discovery endpoint. Without a saved
+session both flags are required; a saved session supplies both together. No MCP
+defaults, admin login, or automatic candidate selection are used:
 
 ```bash
 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
+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`
+needs an AMS build that serves `/agents/{agent_id}/configuration/export`; that
+route is not yet deployed to dev:
+
+```bash
+uv run --frozen hc ams agents list --environment dev --tenant-id TENANT_ID
+uv run --frozen hc ams agents get --environment dev --tenant-id TENANT_ID --agent-id AGENT_ID
+uv run --frozen hc ams agents export --environment dev --tenant-id TENANT_ID --agent-id AGENT_ID \
+  --format yaml --out agent.yaml
+```
+
+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,
+and evaluation-suite content are never included in the projection:
+
+```bash
+uv run --frozen hc ams departments list --environment dev --tenant-id TENANT_ID
+uv run --frozen hc ams departments get --environment dev --tenant-id TENANT_ID \
+  --department-id DEPARTMENT_ID
+```
+
+Department reads are complete and unpaged. The CLI does not expose department
+create, update, delete, activate, or deactivate operations.
+
+Read-only team listing and inspection are also complete and unpaged. The bounded
+projection omits descriptions and creator identities; it includes evaluation-suite
+IDs but never suite content. The CLI does not expose team mutations:
+
+```bash
+uv run --frozen hc ams teams list --environment dev --tenant-id TENANT_ID
+uv run --frozen hc ams teams get --environment dev --tenant-id TENANT_ID --team-id TEAM_ID
+```
+
+The organization hierarchy is the backend-built department/team/agent tree. The
+CLI preserves its order and nesting without issuing entity reads, joining records,
+or inferring missing relationships:
+
+```bash
+uv run --frozen hc ams organization hierarchy --environment dev --tenant-id TENANT_ID
+```
+
+Read-only skill catalog listing and inspection are complete and unpaged. The
+bounded projection includes only skill IDs, names, tool IDs, and audit timestamps;
+it omits descriptions, tenant identity, creator identity, arbitrary response
+fields, and tool details. Tool-ID order is preserved:
+
+```bash
+uv run --frozen hc ams skills list --environment dev --tenant-id TENANT_ID
+uv run --frozen hc ams skills get --environment dev --tenant-id TENANT_ID --skill-id SKILL_ID
+```
+
+The CLI does not create, update, delete, or assign skills. Skill commands do not
+read guardrails. They make exactly one catalog GET after tenant-admin login
+and does not paginate, retry, cache, join, or infer additional catalog data.
+Skill reads refuse target files, root credentials or base URLs, raw output,
+blank or dot-segment skill IDs, and installed SDKs that do not provide both
+skill list and get methods. These local refusals happen before tenant-admin login
+or catalog reads.
+
+Read-only policy catalog listing and inspection are complete and unpaged. The
+bounded projection includes only policy IDs, names, department IDs, guardrail
+IDs, active status, and audit timestamps. It never emits protected policy
+content, descriptions, tenant or creator identity, arbitrary response fields,
+or joined department/guardrail details. Guardrail-ID order is preserved:
+
+```bash
+uv run --frozen hc ams policies list --environment dev --tenant-id TENANT_ID
+uv run --frozen hc ams policies get --environment dev --tenant-id TENANT_ID --policy-id POLICY_ID
+```
+
+The CLI does not export protected policy content; create, update, delete, or
+assign policies; or join guardrail records. It makes exactly one catalog GET after
+tenant-admin login and does not paginate, retry, cache, join, or infer referenced
+resources. Policy reads refuse target files, root credentials or base URLs, raw
+output, blank or dot-segment policy IDs, and installed SDKs without both policy
+methods before tenant-admin login or catalog reads. Successful reads make no
+assignment, deployment, serving, enforcement, or effectiveness claim.
+
+Read-only guardrail catalog listing and inspection are complete and unpaged.
+The bounded projection includes only guardrail IDs, names, and audit timestamps.
+It never emits protected rules, descriptions, tenant or creator identity,
+arbitrary response fields, or joined policy/agent details:
+
+```bash
+uv run --frozen hc ams guardrails list --environment dev --tenant-id TENANT_ID
+uv run --frozen hc ams guardrails get --environment dev --tenant-id TENANT_ID \
+  --guardrail-id GUARDRAIL_ID
+```
+
+The CLI does not export rules; create, update, delete, assign, deploy, or enforce
+guardrails; or claim they are active or effective. It makes exactly one catalog
+GET after tenant-admin login and does not paginate, retry, cache, join, or infer
+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.
+
 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
@@ -355,11 +489,11 @@ configuration and recheck it before apply and selected-field restore. This is an
 operator prerequisite: the current CLI does not automatically attest deployment
 or all-writer coverage, and the record adds no server authorization boundary.
 
-Credentials enter only through `HC_AMS_ADMIN_EMAIL` and `HC_AMS_ADMIN_PASSWORD`
-in the current process, intended for composition with the existing
-`onepassword-env` wrapper. Each invocation logs in through `HCTenantAdminSDK`;
-tokens remain private in memory. There is no token cache, fallback identity,
-secret argument, resolved env file, or browser credential bridge. Root MCP
+For CI and scripts with no saved session, credentials may still enter through
+`HC_AMS_ADMIN_EMAIL` and `HC_AMS_ADMIN_PASSWORD` in the current process, intended
+for composition with the existing `onepassword-env` wrapper; that compatibility
+path logs in once per invocation. There is no fallback identity, secret argument,
+arbitrary token import, resolved env file, keychain, or browser credential bridge. Root MCP
 `--access-token`, `--base-url`, their environment equivalents, and token/base-URL
 profiles are refused for AMS. Root profile environment values do not select AMS.
 

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

@@ -51,10 +51,10 @@ _HC_COMPLETE=bash_complete COMP_WORDS="hc ams inspect --o" COMP_CWORD=3 uv run -
 ```
 
 Operational validation starts only when Click invokes an AMS leaf callback.
-`discover` then validates its explicit environment and tenant arguments; the
-other leaves require `--target-file` and apply the existing root, target, and
-authentication checks described below. Deferring preflight does not relax
-those safety requirements.
+`discover`, `agents`, `departments`, `teams`, `organization`, `skills`, and `policies` then
+validate their explicit environment and tenant arguments; the remaining leaves
+require `--target-file`. All apply the root, target, and authentication checks
+described below. Deferring preflight does not relax those safety requirements.
 
 The bundled tool manifest (`healthcloud_cli/contracts/mcp-tools.manifest.json`)
 is a copy of `packages/cli/contracts/mcp-tools.manifest.json`. Re-sync it
@@ -262,13 +262,147 @@ uv sync --frozen --extra dev
 uv run --frozen hc ams --help
 ```
 
-Bootstrap candidate IDs with the public SDK discovery endpoint. Both flags are
-required; no MCP defaults, admin login, or automatic candidate selection are used:
+Create one private tenant-admin session before interactive AMS work, inspect its
+non-secret binding, and remove it when finished:
+
+```bash
+uv run --frozen hc login --environment dev --tenant-id TENANT_ID
+uv run --frozen hc login --status
+uv run --frozen hc logout
+```
+
+`hc login` reads `HC_AMS_ADMIN_EMAIL` and `HC_AMS_ADMIN_PASSWORD` when present,
+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.
+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
+expiry is refreshed once before the operation, under a lock so concurrent
+commands never spend the same refresh token (a second command waits up to 30 seconds, then stops), and
+atomically replaced. Refresh
+failure stops without an AMS call or password fallback and asks for a new login.
+If the refreshed session cannot be saved, the current command still finishes and
+prints a warning to run `hc login` again.
+
+`~/.healthcloud` and `~/.healthcloud/cli` must be directories you own with mode
+700; the CLI creates them that way, and refuses (naming the directory and the
+`chmod 700` fix) if an existing one is shared. `hc logout` deletes the local file
+only and reports `"server_session_revoked": false`: issued tokens stay valid
+until they expire.
+
+Bootstrap candidate IDs with the public SDK discovery endpoint. Without a saved
+session both flags are required; a saved session supplies both together. No MCP
+defaults, admin login, or automatic candidate selection are used:
 
 ```bash
 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
+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`
+needs an AMS build that serves `/agents/{agent_id}/configuration/export`; that
+route is not yet deployed to dev:
+
+```bash
+uv run --frozen hc ams agents list --environment dev --tenant-id TENANT_ID
+uv run --frozen hc ams agents get --environment dev --tenant-id TENANT_ID --agent-id AGENT_ID
+uv run --frozen hc ams agents export --environment dev --tenant-id TENANT_ID --agent-id AGENT_ID \
+  --format yaml --out agent.yaml
+```
+
+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,
+and evaluation-suite content are never included in the projection:
+
+```bash
+uv run --frozen hc ams departments list --environment dev --tenant-id TENANT_ID
+uv run --frozen hc ams departments get --environment dev --tenant-id TENANT_ID \
+  --department-id DEPARTMENT_ID
+```
+
+Department reads are complete and unpaged. The CLI does not expose department
+create, update, delete, activate, or deactivate operations.
+
+Read-only team listing and inspection are also complete and unpaged. The bounded
+projection omits descriptions and creator identities; it includes evaluation-suite
+IDs but never suite content. The CLI does not expose team mutations:
+
+```bash
+uv run --frozen hc ams teams list --environment dev --tenant-id TENANT_ID
+uv run --frozen hc ams teams get --environment dev --tenant-id TENANT_ID --team-id TEAM_ID
+```
+
+The organization hierarchy is the backend-built department/team/agent tree. The
+CLI preserves its order and nesting without issuing entity reads, joining records,
+or inferring missing relationships:
+
+```bash
+uv run --frozen hc ams organization hierarchy --environment dev --tenant-id TENANT_ID
+```
+
+Read-only skill catalog listing and inspection are complete and unpaged. The
+bounded projection includes only skill IDs, names, tool IDs, and audit timestamps;
+it omits descriptions, tenant identity, creator identity, arbitrary response
+fields, and tool details. Tool-ID order is preserved:
+
+```bash
+uv run --frozen hc ams skills list --environment dev --tenant-id TENANT_ID
+uv run --frozen hc ams skills get --environment dev --tenant-id TENANT_ID --skill-id SKILL_ID
+```
+
+The CLI does not create, update, delete, or assign skills. Skill commands do not
+read guardrails. They make exactly one catalog GET after tenant-admin login
+and does not paginate, retry, cache, join, or infer additional catalog data.
+Skill reads refuse target files, root credentials or base URLs, raw output,
+blank or dot-segment skill IDs, and installed SDKs that do not provide both
+skill list and get methods. These local refusals happen before tenant-admin login
+or catalog reads.
+
+Read-only policy catalog listing and inspection are complete and unpaged. The
+bounded projection includes only policy IDs, names, department IDs, guardrail
+IDs, active status, and audit timestamps. It never emits protected policy
+content, descriptions, tenant or creator identity, arbitrary response fields,
+or joined department/guardrail details. Guardrail-ID order is preserved:
+
+```bash
+uv run --frozen hc ams policies list --environment dev --tenant-id TENANT_ID
+uv run --frozen hc ams policies get --environment dev --tenant-id TENANT_ID --policy-id POLICY_ID
+```
+
+The CLI does not export protected policy content; create, update, delete, or
+assign policies; or join guardrail records. It makes exactly one catalog GET after
+tenant-admin login and does not paginate, retry, cache, join, or infer referenced
+resources. Policy reads refuse target files, root credentials or base URLs, raw
+output, blank or dot-segment policy IDs, and installed SDKs without both policy
+methods before tenant-admin login or catalog reads. Successful reads make no
+assignment, deployment, serving, enforcement, or effectiveness claim.
+
+Read-only guardrail catalog listing and inspection are complete and unpaged.
+The bounded projection includes only guardrail IDs, names, and audit timestamps.
+It never emits protected rules, descriptions, tenant or creator identity,
+arbitrary response fields, or joined policy/agent details:
+
+```bash
+uv run --frozen hc ams guardrails list --environment dev --tenant-id TENANT_ID
+uv run --frozen hc ams guardrails get --environment dev --tenant-id TENANT_ID \
+  --guardrail-id GUARDRAIL_ID
+```
+
+The CLI does not export rules; create, update, delete, assign, deploy, or enforce
+guardrails; or claim they are active or effective. It makes exactly one catalog
+GET after tenant-admin login and does not paginate, retry, cache, join, or infer
+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.
+
 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
@@ -337,11 +471,11 @@ configuration and recheck it before apply and selected-field restore. This is an
 operator prerequisite: the current CLI does not automatically attest deployment
 or all-writer coverage, and the record adds no server authorization boundary.
 
-Credentials enter only through `HC_AMS_ADMIN_EMAIL` and `HC_AMS_ADMIN_PASSWORD`
-in the current process, intended for composition with the existing
-`onepassword-env` wrapper. Each invocation logs in through `HCTenantAdminSDK`;
-tokens remain private in memory. There is no token cache, fallback identity,
-secret argument, resolved env file, or browser credential bridge. Root MCP
+For CI and scripts with no saved session, credentials may still enter through
+`HC_AMS_ADMIN_EMAIL` and `HC_AMS_ADMIN_PASSWORD` in the current process, intended
+for composition with the existing `onepassword-env` wrapper; that compatibility
+path logs in once per invocation. There is no fallback identity, secret argument,
+arbitrary token import, resolved env file, keychain, or browser credential bridge. Root MCP
 `--access-token`, `--base-url`, their environment equivalents, and token/base-URL
 profiles are refused for AMS. Root profile environment values do not select AMS.
 

healthcloud_cli-3.4.0/healthcloud_cli/ams/agents/__init__.py

@@ -0,0 +1,5 @@
+"""Read-only AMS agent command domain."""
+
+from .group import create_agents_group
+
+__all__ = ["create_agents_group"]

healthcloud_cli-3.4.0/healthcloud_cli/ams/agents/commands.py

@@ -0,0 +1,83 @@
+"""Fresh Click adapters for read-only agent operations."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from ..compatibility import safe_errors
+from ..context import AmsDependencies, pass_ams, preflight_agents
+from ..output import metadata
+from ..session import resolve_tenant_target
+from .operations import AgentReadRefused, export_agent, get_agent, list_agents
+
+
+def _environment(function):
+    return click.option("--environment", type=click.Choice(["dev", "uat", "prod"]))(function)
+
+
+def _tenant(function):
+    return click.option("--tenant-id")(function)
+
+
+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)))
+
+    return command
+
+
+def create_get_command(dependencies: AmsDependencies) -> click.Command:
+    @click.command("get")
+    @_environment
+    @_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))
+
+    return command
+
+
+def create_export_command(dependencies: AmsDependencies) -> click.Command:
+    @click.command("export")
+    @_environment
+    @_tenant
+    @_agent
+    @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,
+        tenant_id: str | None,
+        agent_id: str,
+        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))
+
+    return command

healthcloud_cli-3.4.0/healthcloud_cli/ams/agents/group.py

@@ -0,0 +1,18 @@
+"""Fresh agent-domain group assembly."""
+
+from __future__ import annotations
+
+import click
+
+from ..context import AmsDependencies
+from .commands import create_export_command, create_get_command, create_list_command
+
+
+def create_agents_group(dependencies: AmsDependencies) -> click.Group:
+    @click.group("agents")
+    def group() -> None:
+        """Read-only agent listing, inspection and export for one explicit tenant."""
+
+    for factory in (create_list_command, create_get_command, create_export_command):
+        group.add_command(factory(dependencies))
+    return group

healthcloud_cli-3.4.0/healthcloud_cli/ams/agents/operations.py

@@ -0,0 +1,72 @@
+"""Click-free orchestration for agent list, get, and exact-text export."""
+
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+from typing import Literal
+
+from ..context import AmsDependencies
+from ..output import private_text_output
+from ..target import TenantTarget
+from .projections import detail, summary
+
+
+class AgentReadRefused(ValueError):
+    """A stable refusal safe for the CLI adapter to expose."""
+
+
+def _agent_id(value: str) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise AgentReadRefused("Explicit agent ID required.")
+    return value
+
+
+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],
+    }
+
+
+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.")
+    return agent
+
+
+def get_agent(dependencies: AmsDependencies, target: TenantTarget, agent_id: str) -> dict:
+    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)
+
+
+def export_agent(
+    dependencies: AmsDependencies,
+    target: TenantTarget,
+    agent_id: str,
+    output: Path,
+    export_format: Literal["json", "yaml"],
+) -> dict:
+    agent_id = _agent_id(agent_id)
+    if export_format not in ("json", "yaml"):
+        raise AgentReadRefused("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(),
+    }

healthcloud_cli-3.4.0/healthcloud_cli/ams/agents/projections.py

@@ -0,0 +1,37 @@
+"""Explicit bounded projections for agent reads."""
+
+from __future__ import annotations
+
+from healthcloud.models.ams_tuning import AgentConfig
+
+from ..output import digest
+
+ASSIGNED_REFERENCES = ("tool_ids", "skill_ids", "guardrail_ids", "policy_ids", "data_source_ids")
+
+
+def _metadata_string(value: object) -> str:
+    return value if isinstance(value, str) and value.strip() else "unknown"
+
+
+def summary(agent: AgentConfig) -> dict:
+    runtime = agent.runtime_configuration if isinstance(agent.runtime_configuration, dict) else {}
+    return {
+        "id": agent.id,
+        "name": agent.name,
+        "key": agent.key,
+        "type": agent.type,
+        "status": agent.status,
+        "active": agent.active,
+        "config_version": agent.config_version,
+        "adapter": _metadata_string(runtime.get("adapter")),
+        "runtime": _metadata_string(runtime.get("runtime")),
+    }
+
+
+def detail(agent: AgentConfig) -> dict:
+    values = {"instructions": agent.instructions, "greetings": agent.greetings}
+    return summary(agent) | {
+        "fields": sorted(values),
+        "field_hashes": {key: digest(value) for key, value in values.items()},
+        "assigned_references": {key: getattr(agent, key) for key in ASSIGNED_REFERENCES},
+    }