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

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

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: aac-cli
-Version: 0.2.4
+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.10
+Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 License-File: NOTICE
@@ -59,7 +59,7 @@ pip install aac-cli
 aac --version
 ```
 
-Python 3.10 or newer is required.
+Python 3.11 or newer is required.
 
 > **Mind the name.** `pip install aac` installs an unrelated project that
 > happens to share the acronym. The AAC package is **`aac-cli`**; the
@@ -973,6 +973,7 @@ Deactivation is terminal, and a deactivated SPIFFE id stays reserved.
 ```bash
 aac trust-anchor list --profile prod --output table          # every published key, every lifecycle state
 aac trust-anchor describe --profile prod --kid starter-root-v1
+aac chain list --profile prod --since 7d --output table
 aac chain show --profile prod \
   --token-id c3d5e7f9c3d5e7f9c3d5e7f9c3d5e7f9c3d5e7f9c3d5e7f9c3d5e7f9c3d5e7f9 --output table
 aac chain show --profile prod \
@@ -984,6 +985,18 @@ aac chain show --profile prod \
 chain to any tenant that took part in it. The timeline carries metadata
 only; the business content of each step stays in your own audit stream.
 
+`chain list` discovers roots using central observations for your tenant. The
+default is the last 24 hours; use `--since 7d` or timezone-qualified
+`--from 2026-09-01T00:00Z --to 2026-09-08T00:00Z` for a different interval
+(maximum 31 days). It reads no local files or business labels. JSON includes
+the resolved interval and `next_page_token`; pass that token with
+`--page-token` to continue the same query. Each invocation fetches one page
+(default 50 rows, maximum 200). Tokens expire 15 minutes after the first page.
+Central evidence may be incomplete and pages are live: late forwarding can
+change summaries or add roots, including roots behind the current page.
+Repeat the original interval to refresh. A returned `root_token_id` works
+with `chain show --token-id` and `aeg render --root-token-id`.
+
 ## Getting help
 
 `aac --help` lists the command groups and `aac <command> --help` shows every

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

@@ -1,25 +1,3 @@
-Metadata-Version: 2.4
-Name: aac-cli
-Version: 0.2.4
-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.10
-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).
@@ -59,7 +37,7 @@ pip install aac-cli
 aac --version
 ```
 
-Python 3.10 or newer is required.
+Python 3.11 or newer is required.
 
 > **Mind the name.** `pip install aac` installs an unrelated project that
 > happens to share the acronym. The AAC package is **`aac-cli`**; the
@@ -973,6 +951,7 @@ Deactivation is terminal, and a deactivated SPIFFE id stays reserved.
 ```bash
 aac trust-anchor list --profile prod --output table          # every published key, every lifecycle state
 aac trust-anchor describe --profile prod --kid starter-root-v1
+aac chain list --profile prod --since 7d --output table
 aac chain show --profile prod \
   --token-id c3d5e7f9c3d5e7f9c3d5e7f9c3d5e7f9c3d5e7f9c3d5e7f9c3d5e7f9c3d5e7f9 --output table
 aac chain show --profile prod \
@@ -984,6 +963,18 @@ aac chain show --profile prod \
 chain to any tenant that took part in it. The timeline carries metadata
 only; the business content of each step stays in your own audit stream.
 
+`chain list` discovers roots using central observations for your tenant. The
+default is the last 24 hours; use `--since 7d` or timezone-qualified
+`--from 2026-09-01T00:00Z --to 2026-09-08T00:00Z` for a different interval
+(maximum 31 days). It reads no local files or business labels. JSON includes
+the resolved interval and `next_page_token`; pass that token with
+`--page-token` to continue the same query. Each invocation fetches one page
+(default 50 rows, maximum 200). Tokens expire 15 minutes after the first page.
+Central evidence may be incomplete and pages are live: late forwarding can
+change summaries or add roots, including roots behind the current page.
+Repeat the original interval to refresh. A returned `root_token_id` works
+with `chain show --token-id` and `aeg render --root-token-id`.
+
 ## Getting help
 
 `aac --help` lists the command groups and `aac <command> --help` shows every

{aac_cli-0.2.4 → aac_cli-0.2.5}/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.4"
+__version__ = "0.2.5"

aac_cli-0.2.5/aac_cli/chain_list.py

@@ -0,0 +1,100 @@
+"""Public chain-list query preparation and table rendering; no server dependency."""
+
+from __future__ import annotations
+
+import re
+from datetime import datetime, timedelta, timezone
+
+MAX_WINDOW_SECONDS = 31 * 86400
+MAX_LIMIT = 200
+_TIME_RE = re.compile(
+    r"[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}(?::[0-9]{2}(?:\.(?P<fraction>[0-9]{1,6}))?)?"
+    r"(?:Z|[+-](?:[01][0-9]|2[0-3]):[0-5][0-9])"
+)
+
+
+def _time(value: str) -> datetime:
+    match = _TIME_RE.fullmatch(value)
+    if match is None:
+        raise ValueError("--from/--to require timezone-qualified RFC3339 timestamps")
+    fraction = match.group("fraction")
+    if fraction is not None:
+        # Pad exactly, without rounding: every accepted 1..6-digit fraction
+        # then parses identically on every supported interpreter.
+        value = (
+            value[: match.start("fraction")]
+            + fraction.ljust(6, "0")
+            + value[match.end("fraction") :]
+        )
+    try:
+        return datetime.fromisoformat(value.replace("Z", "+00:00")).astimezone(timezone.utc)
+    except (ValueError, OverflowError) as exc:
+        raise ValueError("--from/--to require valid RFC3339 timestamps") from exc
+
+
+def query_params(
+    *,
+    since: str | None,
+    start: str | None,
+    end: str | None,
+    limit: int | None,
+    page_token: str | None,
+    now: datetime | None = None,
+) -> dict[str, str]:
+    if limit is not None and not 1 <= limit <= MAX_LIMIT:
+        raise ValueError("--limit must be between 1 and 200")
+    if (start is None) != (end is None):
+        raise ValueError("--from and --to must be supplied together")
+    if since is not None and (start is not None or page_token is not None):
+        raise ValueError("--since cannot be combined with --from/--to or --page-token")
+    params = {}
+    if limit is not None:
+        params["limit"] = str(limit)
+    if page_token is not None:
+        if not page_token or len(page_token) > 2048:
+            raise ValueError("--page-token must contain 1 to 2048 characters")
+        params["cursor"] = page_token
+    if start is not None and end is not None:
+        from_time, to_time = _time(start), _time(end)
+    elif page_token is not None:
+        return params  # Server reuses the original resolved interval/limit.
+    else:
+        duration = since or "24h"
+        match = re.fullmatch(r"([0-9]{1,4})([hd])", duration)
+        if match is None:
+            raise ValueError("--since requires positive integer hours or days, such as 24h or 7d")
+        seconds = int(match[1]) * (3600 if match[2] == "h" else 86400)
+        if not 0 < seconds <= MAX_WINDOW_SECONDS:
+            raise ValueError("--since must be greater than zero and at most 31 days")
+        to_time = now or datetime.now(timezone.utc)
+        from_time = to_time - timedelta(seconds=seconds)
+    if not timedelta(0) < to_time - from_time <= timedelta(seconds=MAX_WINDOW_SECONDS):
+        raise ValueError("--from must precede --to by at most 31 days")
+    params.update(
+        {
+            "from": from_time.isoformat().replace("+00:00", "Z"),
+            "to": to_time.isoformat().replace("+00:00", "Z"),
+        }
+    )
+    return params
+
+
+def render_table(body: dict) -> str:
+    lines = [
+        "Central observations may be incomplete (best-effort forwarding).",
+        f"Activity interval: [{body['from']}, {body['to']}) — live pagination",
+        "Times, token counts and hop indexes are observed, not execution totals.",
+        "",
+        "root_token_id                                                     first_event  last_event   tokens max_hop outcomes",
+    ]
+    for row in body["chains"]:
+        lines.append(
+            f"{row['root_token_id']}  {row['first_event_unix_seconds']:<12} "
+            f"{row['last_event_unix_seconds']:<12} {row['observed_token_count']:<6} "
+            f"{row['max_observed_hop']:<7} {','.join(row['outcomes'])}"
+        )
+    if body["has_more"]:
+        lines.append(f"\nMore results: repeat with --page-token {body['next_page_token']}")
+    else:
+        lines.append("\nNo more rows in this query; late observations can change a repeat query.")
+    return "\n".join(lines)

{aac_cli-0.2.4 → aac_cli-0.2.5}/aac_cli/cli.py

@@ -3020,6 +3020,27 @@ def _cmd_chain_show(args: argparse.Namespace) -> int:
     return 0
 
 
+def _cmd_chain_list(args: argparse.Namespace) -> int:
+    from .chain_list import query_params, render_table
+
+    try:
+        params = query_params(
+            since=args.since,
+            start=args.from_time,
+            end=args.to_time,
+            limit=args.limit,
+            page_token=args.page_token,
+        )
+    except ValueError as exc:
+        raise CliUsageError(str(exc)) from exc
+    code, body = _data_plane_get(args, "/v1/trace/chains", params)
+    if code:
+        return code
+    assert body is not None
+    print(json.dumps(body, indent=2) if args.output == "json" else render_table(body))
+    return 0
+
+
 # ---------------------------------------------------------------------------
 # aac trust-anchor list / describe / ingest-history (B130) / revoke (B201)
 # ---------------------------------------------------------------------------
@@ -5280,8 +5301,45 @@ def build_parser() -> argparse.ArgumentParser:
     )
     ta_history.set_defaults(handler=_cmd_trust_anchor_ingest_history)
 
-    chain = nouns.add_parser("chain", help="Per-chain audit operations.")
+    chain = nouns.add_parser("chain", help="Discover chains and inspect their audit observations.")
     chain_verbs = chain.add_subparsers(dest="verb", required=True)
+    chain_list = chain_verbs.add_parser(
+        "list",
+        help="List observed chains visible to your tenant.",
+        description="Query central observations only; no local files are read. Central evidence may be incomplete because forwarding is best effort.",
+        epilog="Each invocation fetches one page. Continue using --page-token alone to preserve the resolved interval and page size. Pagination is live: late arrivals can change rows or be missed before the last returned root. Repeat the original interval to refresh. Connected composite roots remain distinct rows. Times, outcomes and counts are observations, not chain completion or execution totals.",
+    )
+    _add_common_flags(chain_list)
+    chain_list.add_argument("--tenant-id", default=None, help="Credential to present.")
+    chain_list.add_argument(
+        "--since",
+        default=None,
+        help="Positive integer hours or days (default 24h; maximum 31d). Cannot accompany a page token or explicit interval.",
+    )
+    chain_list.add_argument(
+        "--from",
+        dest="from_time",
+        default=None,
+        help="Inclusive RFC3339 activity time with timezone; requires --to.",
+    )
+    chain_list.add_argument(
+        "--to",
+        dest="to_time",
+        default=None,
+        help="Exclusive RFC3339 activity time with timezone; requires --from. Maximum interval 31 days.",
+    )
+    chain_list.add_argument(
+        "--limit",
+        type=int,
+        default=None,
+        help="Rows per page (default 50, maximum 200; continuation preserves original size).",
+    )
+    chain_list.add_argument(
+        "--page-token",
+        default=None,
+        help="Opaque continuation from next_page_token (expires after 15 minutes).",
+    )
+    chain_list.set_defaults(handler=_cmd_chain_list)
     show = chain_verbs.add_parser(
         "show", help="Chronological cross-org timeline (participant tenants only)."
     )

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

@@ -1,3 +1,25 @@
+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).
@@ -37,7 +59,7 @@ pip install aac-cli
 aac --version
 ```
 
-Python 3.10 or newer is required.
+Python 3.11 or newer is required.
 
 > **Mind the name.** `pip install aac` installs an unrelated project that
 > happens to share the acronym. The AAC package is **`aac-cli`**; the
@@ -951,6 +973,7 @@ Deactivation is terminal, and a deactivated SPIFFE id stays reserved.
 ```bash
 aac trust-anchor list --profile prod --output table          # every published key, every lifecycle state
 aac trust-anchor describe --profile prod --kid starter-root-v1
+aac chain list --profile prod --since 7d --output table
 aac chain show --profile prod \
   --token-id c3d5e7f9c3d5e7f9c3d5e7f9c3d5e7f9c3d5e7f9c3d5e7f9c3d5e7f9c3d5e7f9 --output table
 aac chain show --profile prod \
@@ -962,6 +985,18 @@ aac chain show --profile prod \
 chain to any tenant that took part in it. The timeline carries metadata
 only; the business content of each step stays in your own audit stream.
 
+`chain list` discovers roots using central observations for your tenant. The
+default is the last 24 hours; use `--since 7d` or timezone-qualified
+`--from 2026-09-01T00:00Z --to 2026-09-08T00:00Z` for a different interval
+(maximum 31 days). It reads no local files or business labels. JSON includes
+the resolved interval and `next_page_token`; pass that token with
+`--page-token` to continue the same query. Each invocation fetches one page
+(default 50 rows, maximum 200). Tokens expire 15 minutes after the first page.
+Central evidence may be incomplete and pages are live: late forwarding can
+change summaries or add roots, including roots behind the current page.
+Repeat the original interval to refresh. A returned `root_token_id` works
+with `chain show --token-id` and `aeg render --root-token-id`.
+
 ## Getting help
 
 `aac --help` lists the command groups and `aac <command> --help` shows every

{aac_cli-0.2.4 → aac_cli-0.2.5}/aac_cli.egg-info/SOURCES.txt

@@ -14,6 +14,7 @@ aac_cli/agent_health.py
 aac_cli/agent_layout.py
 aac_cli/agent_record.py
 aac_cli/api_key_rotation_state.py
+aac_cli/chain_list.py
 aac_cli/cli.py
 aac_cli/config.py
 aac_cli/config_render.py

{aac_cli-0.2.4 → aac_cli-0.2.5}/pyproject.toml

@@ -32,10 +32,10 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "aac-cli"
-version = "0.2.4"
+version = "0.2.5"
 description = "The aac platform CLI — headless operator interface to the AAC control plane (tenant registration, chain audit)."
 readme = "README.md"
-requires-python = ">=3.10"
+requires-python = ">=3.11"
 license = "Apache-2.0"
 # PEP 639: the license FILE ships in the wheel's dist-info/licenses/
 # (B119 — required for the PyPI channel; same pattern as
@@ -46,8 +46,8 @@ authors = [{ name = "Agent Authority Cloud Project" }]
 dependencies = [
     # HTTP client (same floor as the workspace).
     # Config is stdlib configparser (INI — the AWS-CLI idiom,
-    # user-ratified Week 13 over TOML/YAML: zero-dep and our 3.10 floor
-    # predates stdlib tomllib anyway).
+    # user-ratified Week 13 over TOML/YAML: zero-dep; the floor at
+    # ratification, 3.10, predated stdlib tomllib).
     "httpx>=0.28",
     # B144: local Ed25519 recovery-key generation, proof signing, and
     # public-key fingerprint derivation. Private material never leaves the CLI.