aac-cli 0.2.5__tar.gz → 0.2.7__tar.gz

{aac_cli-0.2.5 → aac_cli-0.2.7}/PKG-INFO

@@ -1,10 +1,15 @@
 Metadata-Version: 2.4
 Name: aac-cli
-Version: 0.2.5
+Version: 0.2.7
 Summary: The aac platform CLI — headless operator interface to the AAC control plane (tenant registration, chain audit).
 Author: Agent Authority Cloud Project
 License-Expression: Apache-2.0
-Project-URL: Documentation, https://cascadeauth.github.io/aac-starter-guide/aeg.html
+Project-URL: Documentation, https://cascadeauth.github.io/aac-starter-guide/cli/
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -32,6 +37,10 @@ incoming ones against public trust material the tenant publishes.
 New to AAC? [What AAC is for](https://cascadeauth.github.io/aac-starter-guide/#what-aac-is-for)
 explains what delegated authority between agents buys you, and what it does not.
 
+The [CLI user guide and complete command reference](https://cascadeauth.github.io/aac-starter-guide/cli/)
+cover developer and enterprise onboarding, everyday administration and recovery.
+Select documentation matching `aac --version`.
+
 The `aac` command is how a tenant's operator does everything that is not
 done by the sidecar itself: register the tenant, sign in, manage keys,
 workloads and domains, and prepare a runnable local workload. Everything
@@ -59,7 +68,7 @@ pip install aac-cli
 aac --version
 ```
 
-Python 3.11 or newer is required.
+Python 3.11 to 3.14 is supported. Release checks test all four versions.
 
 > **Mind the name.** `pip install aac` installs an unrelated project that
 > happens to share the acronym. The AAC package is **`aac-cli`**; the
@@ -69,8 +78,13 @@ Python 3.11 or newer is required.
 
 Installing or upgrading `aac-cli` supplies both `aac` and `aeg`.
 Use the [AEG guide and command reference](https://cascadeauth.github.io/aac-starter-guide/aeg.html)
-for rendering local evidence, selecting a profile, and migrating an older
-standalone AEG installation.
+for listing local and central observations, rendering evidence, and selecting a profile.
+
+`aeg list --profile PROFILE --since 7d` discovers participant-visible central
+roots. Add `--events FILE` and/or `--actions FILE` for a hybrid listing with local
+task references and a `local`, `control-plane` or `both` source column. Omit the
+profile for offline local listing. Central fetches are bounded and expose
+continuation; forwarding remains best-effort. Local files are never uploaded.
 
 ## Guided setup using `aac init`
 
@@ -381,7 +395,7 @@ issues them for those names or checks supplied certificates against them; renewa
 keeps those names. Applying a different name set requires the installed certificate
 to cover it already: supplied issuers can issue a certificate covering both sets
 before the change. A CLI-issued agent needing new names must be created under a
-new name with the intended configuration. No old agent-record format is migrated.
+new name with the intended configuration.
 
 Central forwarding retains the local sink and sends only permitted metadata.
 It is asynchronous and best-effort; a local event does not prove central delivery.
@@ -791,6 +805,15 @@ AAC.
 
 ## Output and exit codes
 
+For scripts, `aac profile show NAME --field tenant-id` prints the effective
+tenant ID (including `AAC_TENANT_ID` overrides), and
+`aac tenant assign-hosted-domain --field trust-domain` prints the validated
+server-returned domain. Existing agents expose read-only identities through
+`aac agent status --agent NAME --field tenant-id`, `--field hosted-trust-domain`
+or `--field workload-spiffe-id`. A successful scalar is one unquoted line;
+an unavailable value or unhealthy agent fails with empty stdout. `--field`
+cannot be combined with explicit `--output`, or with agent `--remote`.
+
 Every command that reports a result prints one JSON document to standard
 output by default, with progress notes and diagnostics on standard error,
 so the JSON stays parseable in scripts; `--output table` prints a readable

aac_cli-0.2.5/aac_cli.egg-info/PKG-INFO → aac_cli-0.2.7/README.md

@@ -1,25 +1,3 @@
-Metadata-Version: 2.4
-Name: aac-cli
-Version: 0.2.5
-Summary: The aac platform CLI — headless operator interface to the AAC control plane (tenant registration, chain audit).
-Author: Agent Authority Cloud Project
-License-Expression: Apache-2.0
-Project-URL: Documentation, https://cascadeauth.github.io/aac-starter-guide/aeg.html
-Requires-Python: >=3.11
-Description-Content-Type: text/markdown
-License-File: LICENSE
-License-File: NOTICE
-License-File: THIRD_PARTY_NOTICES.md
-Requires-Dist: httpx>=0.28
-Requires-Dist: cryptography>=42.0
-Requires-Dist: PyYAML>=6.0
-Requires-Dist: pyvis<0.4,>=0.3.2
-Requires-Dist: jsonschema>=4.18
-Provides-Extra: test
-Requires-Dist: pytest>=8.0; extra == "test"
-Requires-Dist: pytest-httpx>=0.30; extra == "test"
-Dynamic: license-file
-
 # aac-cli — the `aac` command
 
 `aac` is the command-line tool for tenants of Agent Authority Cloud (AAC).
@@ -32,6 +10,10 @@ incoming ones against public trust material the tenant publishes.
 New to AAC? [What AAC is for](https://cascadeauth.github.io/aac-starter-guide/#what-aac-is-for)
 explains what delegated authority between agents buys you, and what it does not.
 
+The [CLI user guide and complete command reference](https://cascadeauth.github.io/aac-starter-guide/cli/)
+cover developer and enterprise onboarding, everyday administration and recovery.
+Select documentation matching `aac --version`.
+
 The `aac` command is how a tenant's operator does everything that is not
 done by the sidecar itself: register the tenant, sign in, manage keys,
 workloads and domains, and prepare a runnable local workload. Everything
@@ -59,7 +41,7 @@ pip install aac-cli
 aac --version
 ```
 
-Python 3.11 or newer is required.
+Python 3.11 to 3.14 is supported. Release checks test all four versions.
 
 > **Mind the name.** `pip install aac` installs an unrelated project that
 > happens to share the acronym. The AAC package is **`aac-cli`**; the
@@ -69,8 +51,13 @@ Python 3.11 or newer is required.
 
 Installing or upgrading `aac-cli` supplies both `aac` and `aeg`.
 Use the [AEG guide and command reference](https://cascadeauth.github.io/aac-starter-guide/aeg.html)
-for rendering local evidence, selecting a profile, and migrating an older
-standalone AEG installation.
+for listing local and central observations, rendering evidence, and selecting a profile.
+
+`aeg list --profile PROFILE --since 7d` discovers participant-visible central
+roots. Add `--events FILE` and/or `--actions FILE` for a hybrid listing with local
+task references and a `local`, `control-plane` or `both` source column. Omit the
+profile for offline local listing. Central fetches are bounded and expose
+continuation; forwarding remains best-effort. Local files are never uploaded.
 
 ## Guided setup using `aac init`
 
@@ -381,7 +368,7 @@ issues them for those names or checks supplied certificates against them; renewa
 keeps those names. Applying a different name set requires the installed certificate
 to cover it already: supplied issuers can issue a certificate covering both sets
 before the change. A CLI-issued agent needing new names must be created under a
-new name with the intended configuration. No old agent-record format is migrated.
+new name with the intended configuration.
 
 Central forwarding retains the local sink and sends only permitted metadata.
 It is asynchronous and best-effort; a local event does not prove central delivery.
@@ -791,6 +778,15 @@ AAC.
 
 ## Output and exit codes
 
+For scripts, `aac profile show NAME --field tenant-id` prints the effective
+tenant ID (including `AAC_TENANT_ID` overrides), and
+`aac tenant assign-hosted-domain --field trust-domain` prints the validated
+server-returned domain. Existing agents expose read-only identities through
+`aac agent status --agent NAME --field tenant-id`, `--field hosted-trust-domain`
+or `--field workload-spiffe-id`. A successful scalar is one unquoted line;
+an unavailable value or unhealthy agent fails with empty stdout. `--field`
+cannot be combined with explicit `--output`, or with agent `--remote`.
+
 Every command that reports a result prints one JSON document to standard
 output by default, with progress notes and diagnostics on standard error,
 so the JSON stays parseable in scripts; `--output table` prints a readable

{aac_cli-0.2.5 → aac_cli-0.2.7}/aac_cli/__init__.py

@@ -10,4 +10,4 @@ entrypoint (`aac_cli.cli:entrypoint`).
 # test in bin/tests/test_cli_version_parity.py. A literal keeps the
 # shipped code free of import-time metadata lookups (and their
 # not-installed failure mode).
-__version__ = "0.2.5"
+__version__ = "0.2.7"

{aac_cli-0.2.5 → aac_cli-0.2.7}/aac_cli/_aeg/cli.py

@@ -39,7 +39,7 @@ def parser(
     commands = result.add_subparsers(dest="command", required=True)
     render = commands.add_parser("render", help="Write a self-contained interactive HTML graph.")
     listing = commands.add_parser(
-        "list", help="List candidate roots from explicitly supplied local files."
+        "list", help="List roots from local files, a control-plane profile, or both."
     )
     for command in (render, listing):
         command.add_argument(
@@ -72,9 +72,18 @@ def parser(
     selector.add_argument("--root-token-id", metavar="ID")
     selector.add_argument("--mint-response", type=Path, metavar="FILE")
     render.add_argument("--output", type=Path, required=True, metavar="FILE")
-    listing.add_argument("--task-ref", help="Exact local task reference.")
+    listing.add_argument(
+        "--profile", help="Query this AAC CLI profile; with files, join by root ID."
+    )
+    listing.add_argument("--task-ref", help="Exact local task reference; requires local files.")
+    listing.add_argument("--limit", type=int, help="Central page size, 1..200 (default 50).")
+    listing.add_argument("--max-pages", type=int, help="Central fetch bound, 1..20 (default 1).")
+    listing.add_argument("--page-token", help="Continue central enumeration; omit --since.")
     time_start = listing.add_mutually_exclusive_group()
-    time_start.add_argument("--since", help="Look back from now, e.g. 24h or 7d.")
+    time_start.add_argument(
+        "--since",
+        help="Look back, e.g. 24h or 7d; online defaults to 24h, maximum 31d. Local also accepts m.",
+    )
     time_start.add_argument(
         "--from", dest="from_time", help="Inclusive ISO 8601 observation time with timezone."
     )
@@ -185,11 +194,21 @@ def _date(value: str) -> datetime:
         raise InputError(f"invalid time {value!r}; use ISO 8601 with timezone") from exc
 
 
-def _list(args, events) -> int:
+def _list(args, events, list_query) -> int:
+    if args.profile is not None:
+        if not args.profile.strip():
+            raise InputError("--profile must name an existing AAC CLI profile")
+        if args.task_ref is not None and not (args.events or args.actions):
+            raise InputError(
+                "--task-ref requires local files; the control plane stores no task references"
+            )
+        if list_query is None:
+            raise InputError("online listing requires the aeg command supplied by aac-cli")
+        return list_query(args, events)
     if not (args.events or args.actions):
-        raise InputError(
-            "local list requires --events and/or --actions; profile and hybrid listing belong to a later release"
-        )
+        raise InputError("supply --events, --actions and/or --profile to list roots")
+    if any(value is not None for value in (args.limit, args.max_pages, args.page_token)):
+        raise InputError("--limit, --max-pages and --page-token require --profile")
     start = _date(args.from_time) if args.from_time else None
     stop = _date(args.to_time) if args.to_time else None
     if args.since:
@@ -204,6 +223,13 @@ def _list(args, events) -> int:
             raise InputError("--since duration is outside supported range") from exc
     if start and stop and start > stop:
         raise InputError("--from/--since must precede --to")
+    rows, diagnostics = local_rows(events, args.task_ref, start, stop)
+    print_listing(args.output, rows, diagnostics)
+    return 0
+
+
+def local_rows(events, task_ref, start, stop):
+    """Select local activity, retaining older evidence for token/root correlation."""
     roots, mapping = roots_and_mapping(events)
     diagnostics = [
         f"{e.raw_event.get('_source', e.source)}: unmatched action {e.token_id}; supply sidecar root mapping"
@@ -230,7 +256,7 @@ def _list(args, events) -> int:
                 or (e.raw_event.get("action_payload") or {}).get("task_ref")
             }
         )
-        if args.task_ref and args.task_ref not in task_refs:
+        if task_ref is not None and task_ref not in task_refs:
             continue
         observed = [
             e
@@ -240,36 +266,68 @@ def _list(args, events) -> int:
         ]
         if not observed:
             continue
-        times = sorted(e.timestamp_iso for e in observed)
+        times = sorted(_date(e.timestamp_iso) for e in observed)
         rows.append(
             {
                 "root_token_id": root,
                 "task_refs": task_refs,
-                "first_observed": times[0],
-                "last_observed": times[-1],
+                "first_observed": times[0].isoformat(),
+                "last_observed": times[-1].isoformat(),
                 "sources": "local",
                 "evidence_sources": sorted(
                     {str(e.raw_event.get("_source", e.source)) for e in observed}
                 ),
             }
         )
-    if args.output == "json":
-        print(json.dumps({"chains": rows, "diagnostics": diagnostics}, indent=2))
+    return rows, diagnostics
+
+
+def print_listing(output, rows, diagnostics, coverage=None):
+    if output == "json":
+        body = {"chains": rows, "diagnostics": diagnostics}
+        if coverage is not None:
+            body.update(coverage)
+        print(json.dumps(body, indent=2))
     else:
+        if coverage is not None:
+            central = coverage["central"]
+            print(
+                "Central observations may be incomplete (best-effort forwarding; live pagination)."
+            )
+            if coverage["from"] is None or coverage["to"] is None:
+                print("Activity interval: unknown (continuation failed)")
+            else:
+                print(f"Activity interval: [{coverage['from']}, {coverage['to']})")
+            print(f"Central fetch: {central['status']}; {central['pages_fetched']} page(s).")
+            print("Sources describe this query; local does not mean never received centrally.")
+            print(
+                "Times and hop information are observed, not execution or business-completion totals."
+            )
         print("ROOT TOKEN ID | TASK REFERENCES | FIRST OBSERVED (UTC) | SOURCES")
         for row in rows:
             print(
-                f"{row['root_token_id']} | {', '.join(row['task_refs']) or '(unknown)'} | {row['first_observed']} | local"
+                f"{row['root_token_id']} | {', '.join(row['task_refs']) or '(unknown)'} | {row['first_observed']} | {row['sources']}"
             )
+        if coverage is not None and coverage["central"]["next_page_token"]:
+            cursor = coverage["central"]["next_page_token"]
+            if coverage["central"]["status"] == "failed":
+                print(
+                    f"Retry with --page-token {cursor} only if the failure was transient; "
+                    "otherwise restart the original query."
+                )
+            else:
+                print(
+                    f"Continue with --page-token {cursor} (same profile/files/filter; omit --since)."
+                )
     for diagnostic in diagnostics:
         print(diagnostic, file=sys.stderr)
-    return 0
 
 
 def main(
     argv: list[str] | None = None,
     *,
     query: Query | None = None,
+    list_query: Callable[[argparse.Namespace, list], int] | None = None,
     prog: str = "aeg",
     version_text: str = "shared AAC renderer",
 ) -> int:
@@ -280,7 +338,7 @@ def main(
         return (
             _render(args, events, query or _query)
             if args.command == "render"
-            else _list(args, events)
+            else _list(args, events, list_query)
         )
     except (InputError, ValueError, OSError) as exc:
         for diagnostic in unjoinable_diagnostics(events):

{aac_cli-0.2.5 → aac_cli-0.2.7}/aac_cli/_aeg/data/renderer-source.json

@@ -1,8 +1,8 @@
 {
-  "content_sha256": "e444d19d48410200f040c05bba84d3e2426ecb5ba350430203cad5df74f4104d",
+  "content_sha256": "f0477c0f8e73bffe5e111842d8aca3f5745345acb8cb58bed911deba7d826798",
   "files": {
     "__init__.py": "80d80a1ba35353d271cddf02532801c60b57f5ec06fb268ae823747742ce8979",
-    "cli.py": "b413ca8fffa51f0874deeaad47c16a2bed4ce0ec769074dd566bba3e5480566b",
+    "cli.py": "8fa9605246ba0ddbd24e6034b9582049fac11df139d47ee9e2ee0f322ff53c4c",
     "data/action-taken-v1.json": "d863343afe7f314646a73cf063480a7e650f93857d2ed5ec3a7b1f9838671fdf",
     "data/predicates-v1.json": "35e83a29feada10e8cfbef7009245146a9717d4f4fd58d74124e0ec91ae922c8",
     "from_sidecar.py": "6ac023f6925a13e94e0fee762656a02ca98981f2add194b052e9014ca48e2219",

{aac_cli-0.2.5 → aac_cli-0.2.7}/aac_cli/aeg_cli.py

@@ -21,6 +21,7 @@ def main(argv: list[str] | None = None) -> int:
         return 0
     from ._aeg import cli
     from ._aeg.inputs import InputError, read_trace
+    from .aeg_list import list_chains
 
     def query(profile: str, root: str):
         from .trace_query import query_trace
@@ -30,7 +31,9 @@ def main(argv: list[str] | None = None) -> int:
         except (ValueError, TypeError) as exc:
             raise InputError(str(exc)) from exc
 
-    return cli.main(argv, query=query, prog="aeg", version_text=version_text())
+    return cli.main(
+        argv, query=query, list_query=list_chains, prog="aeg", version_text=version_text()
+    )
 
 
 def entrypoint() -> None:

aac_cli-0.2.7/aac_cli/aeg_list.py

@@ -0,0 +1,173 @@
+"""Bounded AEG discovery over the public chain-list JSON contract."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+from ._aeg.cli import _date, local_rows, print_listing
+from ._aeg.inputs import InputError, token_id
+from .chain_list import query_params
+from .trace_query import query_chains
+
+
+def _observed_time(value) -> str:
+    if type(value) is not int:
+        raise ValueError("expected integer observation time")
+    return datetime.fromtimestamp(value, timezone.utc).isoformat()
+
+
+def _page(body, params, previous_root):
+    """Validate the complete page before adding any of its rows to the result."""
+    try:
+        if (
+            type(body["schema_version"]) is not int
+            or body["schema_version"] != 1
+            or body["pagination"] != "live"
+            or body["central_evidence"] != "best_effort"
+        ):
+            raise ValueError("expected chain-list JSON v1 with live/best-effort evidence")
+        if not isinstance(body["from"], str) or not isinstance(body["to"], str):
+            raise ValueError("expected resolved central interval")
+        window = query_params(
+            since=None,
+            start=body["from"],
+            end=body["to"],
+            limit=body["limit"],
+            page_token=None,
+        )
+        if type(body["limit"]) is not int:
+            raise ValueError("expected integer page limit")
+        if any(window[key] != value for key, value in params.items() if key != "cursor"):
+            raise ValueError("central response changed the requested interval or limit")
+        more, cursor = body["has_more"], body["next_page_token"]
+        if (
+            type(more) is not bool
+            or (more and (not isinstance(cursor, str) or not 1 <= len(cursor) <= 2048))
+            or (not more and cursor is not None)
+        ):
+            raise ValueError("invalid central continuation")
+        if not isinstance(body["chains"], list) or len(body["chains"]) > body["limit"]:
+            raise ValueError("invalid central page rows")
+        if more and not body["chains"]:
+            raise ValueError("empty central page has a continuation")
+        rows = []
+        for item in body["chains"]:
+            root = token_id(item["root_token_id"], "central root")
+            if root <= previous_root:
+                raise ValueError("central roots must advance in ascending order")
+            previous_root = root
+            first = _observed_time(item["first_event_unix_seconds"])
+            last = _observed_time(item["last_event_unix_seconds"])
+            if first > last:
+                raise ValueError("reversed central observation times")
+            for key in ("participant_tenant_ids", "event_categories", "outcomes"):
+                if not isinstance(item[key], list) or not all(
+                    isinstance(v, str) for v in item[key]
+                ):
+                    raise ValueError(f"invalid central {key}")
+            for key in ("observed_token_count", "max_observed_hop"):
+                if type(item[key]) is not int or item[key] < 0:
+                    raise ValueError(f"invalid central {key}")
+            rows.append(
+                {
+                    "root_token_id": root,
+                    "task_refs": [],
+                    "first_observed": first,
+                    "last_observed": last,
+                    "sources": "control-plane",
+                    "evidence_sources": ["control-plane"],
+                    "central_observations": item,
+                }
+            )
+        return window, rows, more, cursor, previous_root
+    except (KeyError, TypeError, ValueError, OverflowError, OSError) as exc:
+        raise InputError(f"incompatible chain-list JSON: {exc}") from exc
+
+
+def list_chains(args, events) -> int:
+    max_pages = args.max_pages if args.max_pages is not None else 1
+    if not 1 <= max_pages <= 20:
+        raise InputError("--max-pages must be between 1 and 20")
+    # Resolve relative time once before any I/O; reuse it for local input and
+    # every page. A bare cursor obtains its bound interval from the first page.
+    params = query_params(
+        since=args.since,
+        start=args.from_time,
+        end=args.to_time,
+        limit=args.limit,
+        page_token=args.page_token,
+    )
+    window = dict(params)
+    central_rows = []
+    diagnostics = []
+    pages = 0
+    more = None
+    cursor = args.page_token
+    status = "failed"
+    previous_root = ""
+    seen_cursors = {cursor} if cursor is not None else set()
+    for _ in range(max_pages):
+        try:
+            body = query_chains(args.profile, params)
+            next_window, rows, next_more, next_cursor, last_root = _page(
+                body, params, previous_root
+            )
+            if next_cursor is not None and next_cursor in seen_cursors:
+                raise InputError("incompatible chain-list JSON: repeated continuation")
+        except (ValueError, TypeError) as exc:
+            diagnostics.append(str(exc))
+            status = "failed"
+            break
+        window = next_window
+        central_rows.extend(rows)
+        pages += 1
+        more, cursor, previous_root = next_more, next_cursor, last_root
+        status = "more" if more else "exhausted"
+        if not more:
+            break
+        seen_cursors.add(cursor)
+        params = {**window, "cursor": cursor}
+
+    if "from" in window and "to" in window:
+        rows, local_diagnostics = local_rows(
+            events, args.task_ref, _date(window["from"]), _date(window["to"])
+        )
+        diagnostics.extend(local_diagnostics)
+    else:
+        rows = []
+        diagnostics.append(
+            "Continuation interval unavailable; local rows cannot be selected. Retry the original interval."
+        )
+    joined = {row["root_token_id"]: row for row in rows}
+    for central in central_rows:
+        root = central["root_token_id"]
+        local = joined.get(root)
+        if local is not None:
+            local.update(
+                {
+                    "sources": "both",
+                    "first_observed": min(local["first_observed"], central["first_observed"]),
+                    "last_observed": max(local["last_observed"], central["last_observed"]),
+                    "evidence_sources": sorted([*local["evidence_sources"], "control-plane"]),
+                    "central_observations": central["central_observations"],
+                }
+            )
+        elif args.task_ref is None:
+            joined[root] = central
+    coverage = {
+        "schema_version": 1,
+        "mode": "hybrid" if args.events or args.actions else "control-plane",
+        "from": window.get("from"),
+        "to": window.get("to"),
+        "central": {
+            "status": status,
+            "pages_fetched": pages,
+            "limit": int(window["limit"]) if "limit" in window else None,
+            "has_more": more,
+            "next_page_token": cursor,
+            "pagination": "live",
+            "evidence": "best_effort",
+        },
+    }
+    print_listing(args.output, [joined[root] for root in sorted(joined)], diagnostics, coverage)
+    return 4 if status == "failed" else 0

{aac_cli-0.2.5 → aac_cli-0.2.7}/aac_cli/agent_cli.py

@@ -47,7 +47,15 @@ from aac_cli.agent_record import (
     read_record,
     write_record,
 )
-from aac_cli.config import CliConfigError, CliUsageError, cli_home, credentials_path
+from aac_cli.config import (
+    CANONICAL_TENANT_ID_PATTERN,
+    JSON_OUTPUT_DEFAULT,
+    CliConfigError,
+    CliUsageError,
+    cli_home,
+    credentials_path,
+    validate_hosted_trust_domain,
+)
 from aac_cli.config_render import configuration_summary, outbound_ca_bundle
 from aac_cli.init_cli import (
     SHARED_MATERIAL_FLAGS,
@@ -88,6 +96,18 @@ def _load(args: argparse.Namespace) -> tuple[AgentPaths, TenantPaths | None, Age
             f"[{wanted}]. The `aac agent` commands find the profile through the agent, so omit "
             f"--profile, or name an agent of profile [{wanted}] with --agent."
         )
+    if getattr(args, "field", None):
+        # Structured status retains its existing diagnostic behavior. Scalar
+        # consumers require a complete canonical identity before any stdout.
+        if not isinstance(record.tenant_id, str) or not CANONICAL_TENANT_ID_PATTERN.fullmatch(
+            record.tenant_id
+        ):
+            raise CliConfigError(f"agent {agent.name!r} has no valid tenant identity")
+        if not isinstance(record.hosted_trust_domain, str):
+            raise CliConfigError(f"agent {agent.name!r} has no valid hosted trust domain")
+        domain = validate_hosted_trust_domain(record.tenant_id, record.hosted_trust_domain)
+        if record.workload_spiffe_id != f"spiffe://{domain}/{record.workload_path}":
+            raise CliConfigError(f"agent {agent.name!r} has an invalid workload identity")
     tenant = tenant_paths(record.tenant_id) if record.tenant_id else None
     return agent, tenant, record
 
@@ -203,8 +223,19 @@ def _inventory_report(
 
 
 def cmd_agent_status(args: argparse.Namespace) -> int:
+    if getattr(args, "field", None) and args.remote:
+        raise CliUsageError("--field reports local identity only; omit --remote")
     agent, tenant, record = _load(args)
     health = assess(agent, tenant, record)
+    if getattr(args, "field", None):
+        value = getattr(record, args.field.replace("-", "_"))
+        if not health.healthy:
+            raise CliConfigError(
+                f"agent {agent.name!r} cannot supply {args.field}: "
+                f"{next_step(agent, tenant, record, health) or 'value unavailable'}"
+            )
+        print(value)
+        return 0
     certificates = {
         label: {
             "not_after": report.not_after,
@@ -603,14 +634,24 @@ def cmd_agent_list(args: argparse.Namespace) -> int:
 # --- parser ----------------------------------------------------------------------------
 
 
-def _agent_flags(parser: argparse.ArgumentParser) -> None:
+def _agent_flags(parser: argparse.ArgumentParser, *, scalar: bool = False) -> None:
     parser.add_argument(
         "--agent",
         required=True,
         help="Target agent name under ~/.aac/agents/.",
     )
-    parser.add_argument(
-        "--output", choices=("json", "table"), default="json", help="Output mode (JSON by default)."
+    output = parser.add_mutually_exclusive_group() if scalar else parser
+    if scalar:
+        output.add_argument(
+            "--field",
+            choices=("tenant-id", "hosted-trust-domain", "workload-spiffe-id"),
+            help="Print one local identity value; fail if unavailable or the agent needs attention. Cannot combine with --output or --remote.",
+        )
+    output.add_argument(
+        "--output",
+        choices=("json", "table"),
+        default=JSON_OUTPUT_DEFAULT if scalar else "json",
+        help="Output mode (JSON by default).",
     )
     parser.add_argument(
         "--profile",
@@ -639,7 +680,7 @@ def add_agent_parser(nouns: argparse._SubParsersAction) -> None:
         "status",
         help="Report what exists, certificate expiry, permission problems and the next command.",
     )
-    _agent_flags(status)
+    _agent_flags(status, scalar=True)
     status.add_argument(
         "--remote",
         action="store_true",

{aac_cli-0.2.5 → aac_cli-0.2.7}/aac_cli/agent_layout.py

@@ -29,9 +29,6 @@ from aac_cli.material_cases import MATERIAL_ISSUED_HERE, MATERIAL_SUPPLIED
 
 TENANTS_DIRECTORY = "tenants"
 AGENTS_DIRECTORY = "agents"
-# 0.1.x kept the same material under `workspaces/`. 0.2.0 is a clean break: an
-# old folder is recognised only so the CLI can say so in one line (B270).
-LEGACY_AGENTS_DIRECTORY = "workspaces"
 
 # Where the container layout expects the mounted directories (matches the
 # public starter guide's Docker recipe so B240 can reuse its mounts).
@@ -249,21 +246,6 @@ def agent_paths(name: str, home: Path | None = None) -> AgentPaths:
     return AgentPaths(name=name, root=(home or cli_home()) / AGENTS_DIRECTORY / name)
 
 
-def legacy_agent_directory(name: str, home: Path | None = None) -> Path:
-    """Where 0.1.x kept this name's material. Read only to refuse it (B270)."""
-    return (home or cli_home()) / LEGACY_AGENTS_DIRECTORY / name
-
-
-def refuse_legacy_directory(name: str, home: Path | None = None) -> None:
-    """One line, no migration: development material is disposable by design."""
-    legacy = legacy_agent_directory(name, home)
-    if legacy.exists():
-        raise CliConfigError(
-            f"{legacy} is from an older CLI and is not migrated; create a new agent with "
-            f"`aac init --agent {name}` after deleting it, or choose another name"
-        )
-
-
 def tenant_paths(tenant_id: str, home: Path | None = None) -> TenantPaths:
     if not CANONICAL_TENANT_ID_PATTERN.fullmatch(tenant_id):
         raise CliConfigError(f"tenant id {tenant_id!r} is not canonical; refusing to derive a path")