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

aac_cli-0.2.5/NOTICE

@@ -0,0 +1,6 @@
+aac-aeg
+Copyright 2026 CascadeAuth contributors.
+
+Interactive output includes vis-network assets provided by pyvis. Their embedded
+license notices are retained in generated HTML. pyvis and its dependencies are
+distributed separately under their own licenses.

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

@@ -1,15 +1,20 @@
 Metadata-Version: 2.4
 Name: aac-cli
-Version: 0.2.3
+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
-Requires-Python: >=3.10
+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"
@@ -37,12 +42,15 @@ result also offers `--output table`.
 Two kinds of tenant use the same tool:
 
 * **Developer tenants** register themselves by signing in with GitHub or
-  Google. `aac init` takes a developer from an installed CLI to a runnable
-  local workload in one command.
+  Google. `aac init` can register the tenant as part of guided agent setup.
 * **Enterprise tenants** are registered through an onboarding ceremony with
-  AAC operations and sign in through their own identity provider. Their
-  keys, domains and workloads are managed with the `aac tenant` and
-  `aac sso` commands described further down.
+  AAC operations and sign in through their own identity provider. After
+  onboarding, they can use the same guided agent setup.
+
+Both kinds use `aac init` to prepare AAC identity, material and configuration
+for an agent; you start the application and its sidecar separately. The
+`aac tenant` and `aac sso` commands described below manage tenants, keys and
+sign-in for both kinds.
 
 ## Install
 
@@ -51,30 +59,51 @@ 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
 > command it installs is **`aac`**.
 
-## Guided setup for developer tenants: `aac init`
-
-`aac init` prepares the AAC side of one of your agents on this machine: it
-registers the agent's identity with AAC and creates the keys, certificates
-and configuration its sidecar needs. The agent itself is yours. The first
-run also creates your profile and registers your tenant; run it again with
-a new `--agent` and its own `--agent-config` file, and the same `--trust-url`
-and `--idp`, for each further agent.
-
-Along the way it signs you in, registers a developer tenant (or reuses the
-one your profile is already bound to), takes the trust domain AAC assigns to the
-tenant, registers your workload, generates development keys and
-certificates, and writes a complete sidecar configuration together with the
-files the trust-anchor publisher and Docker Compose need.
-
-Point it at the endpoints your AAC environment gives you. The example below
-uses the AAC stage environment. First save the YAML example in “Agent configuration”
-below as `orders.yaml`:
+## Use `aeg` to view agent execution graphs
+
+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.
+
+## Guided setup using `aac init`
+
+`aac init` prepares your **AAC CLI home** (`~/.aac` by default) and sets up
+AAC for an agent on this machine: it registers the agent's identity and
+prepares the keys, certificates and configuration its sidecar needs. You
+provide the agent application and start it and its sidecar separately.
+
+The CLI home can hold multiple profiles, tenants and agents. It stores
+profiles, tenant credentials and shared tenant material alongside a separate
+folder for each agent. Each invocation initializes or resumes **one agent**,
+selected by `--agent`. Run it again with the same tenant profile, a new agent
+name and its own `--agent-config` file for each additional agent; existing
+tenant setup is reused. Set `AAC_CLI_HOME` to use a different home directory.
+
+Both developer and enterprise tenants can use this setup. For a new
+developer tenant, the first run also creates the profile and registers the
+tenant. For an enterprise tenant, complete the onboarding steps under
+“Enterprise tenants” below, sign in through its configured identity provider,
+and use a profile bound to that tenant with its active tenant-admin key
+available locally.
+Omit `--idp` for this enterprise flow; that flag selects only GitHub or
+Google developer sign-in. See “Setting up aac-cli on a new computer” below
+for the existing-tenant sign-in and material preparation steps.
+
+Setup uses the tenant's assigned trust domain and writes the files the
+trust-anchor publisher and Docker Compose need, as well as the sidecar
+configuration. By default it generates development keys and certificates;
+the certificate choices below explain how to supply your own instead.
+
+Point it at the endpoints your AAC environment gives you. The developer-tenant
+example below uses the AAC stage environment. First save the YAML example in
+“Agent configuration” below as `orders.yaml`:
 
 ```bash
 aac init --profile stage --agent orders --agent-config orders.yaml \
@@ -944,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 \
@@ -955,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.3/aac_cli.egg-info/PKG-INFO → aac_cli-0.2.5/README.md

@@ -1,20 +1,3 @@
-Metadata-Version: 2.4
-Name: aac-cli
-Version: 0.2.3
-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
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: httpx>=0.28
-Requires-Dist: cryptography>=42.0
-Requires-Dist: PyYAML>=6.0
-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,12 +20,15 @@ result also offers `--output table`.
 Two kinds of tenant use the same tool:
 
 * **Developer tenants** register themselves by signing in with GitHub or
-  Google. `aac init` takes a developer from an installed CLI to a runnable
-  local workload in one command.
+  Google. `aac init` can register the tenant as part of guided agent setup.
 * **Enterprise tenants** are registered through an onboarding ceremony with
-  AAC operations and sign in through their own identity provider. Their
-  keys, domains and workloads are managed with the `aac tenant` and
-  `aac sso` commands described further down.
+  AAC operations and sign in through their own identity provider. After
+  onboarding, they can use the same guided agent setup.
+
+Both kinds use `aac init` to prepare AAC identity, material and configuration
+for an agent; you start the application and its sidecar separately. The
+`aac tenant` and `aac sso` commands described below manage tenants, keys and
+sign-in for both kinds.
 
 ## Install
 
@@ -51,30 +37,51 @@ 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
 > command it installs is **`aac`**.
 
-## Guided setup for developer tenants: `aac init`
-
-`aac init` prepares the AAC side of one of your agents on this machine: it
-registers the agent's identity with AAC and creates the keys, certificates
-and configuration its sidecar needs. The agent itself is yours. The first
-run also creates your profile and registers your tenant; run it again with
-a new `--agent` and its own `--agent-config` file, and the same `--trust-url`
-and `--idp`, for each further agent.
-
-Along the way it signs you in, registers a developer tenant (or reuses the
-one your profile is already bound to), takes the trust domain AAC assigns to the
-tenant, registers your workload, generates development keys and
-certificates, and writes a complete sidecar configuration together with the
-files the trust-anchor publisher and Docker Compose need.
-
-Point it at the endpoints your AAC environment gives you. The example below
-uses the AAC stage environment. First save the YAML example in “Agent configuration”
-below as `orders.yaml`:
+## Use `aeg` to view agent execution graphs
+
+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.
+
+## Guided setup using `aac init`
+
+`aac init` prepares your **AAC CLI home** (`~/.aac` by default) and sets up
+AAC for an agent on this machine: it registers the agent's identity and
+prepares the keys, certificates and configuration its sidecar needs. You
+provide the agent application and start it and its sidecar separately.
+
+The CLI home can hold multiple profiles, tenants and agents. It stores
+profiles, tenant credentials and shared tenant material alongside a separate
+folder for each agent. Each invocation initializes or resumes **one agent**,
+selected by `--agent`. Run it again with the same tenant profile, a new agent
+name and its own `--agent-config` file for each additional agent; existing
+tenant setup is reused. Set `AAC_CLI_HOME` to use a different home directory.
+
+Both developer and enterprise tenants can use this setup. For a new
+developer tenant, the first run also creates the profile and registers the
+tenant. For an enterprise tenant, complete the onboarding steps under
+“Enterprise tenants” below, sign in through its configured identity provider,
+and use a profile bound to that tenant with its active tenant-admin key
+available locally.
+Omit `--idp` for this enterprise flow; that flag selects only GitHub or
+Google developer sign-in. See “Setting up aac-cli on a new computer” below
+for the existing-tenant sign-in and material preparation steps.
+
+Setup uses the tenant's assigned trust domain and writes the files the
+trust-anchor publisher and Docker Compose need, as well as the sidecar
+configuration. By default it generates development keys and certificates;
+the certificate choices below explain how to supply your own instead.
+
+Point it at the endpoints your AAC environment gives you. The developer-tenant
+example below uses the AAC stage environment. First save the YAML example in
+“Agent configuration” below as `orders.yaml`:
 
 ```bash
 aac init --profile stage --agent orders --agent-config orders.yaml \
@@ -944,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 \
@@ -955,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.5/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,46 @@
+# Renderer third-party notices
+
+The renderer uses pyvis 0.3.x, distributed separately as a declared dependency.
+Interactive HTML includes vis-network 9.1.2 assets supplied by pyvis. Embedded
+notices remain in the generated HTML. Other dependencies retain their own
+license material in their distributions.
+
+## pyvis (BSD-3-Clause)
+
+Copyright (c) 2018, West Health Institute
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+ - Redistributions of source code must retain the above copyright notice,
+   this list of conditions and the following disclaimer.
+
+ - Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+ - Neither the name of West Health Institute nor the names of its contributors may
+   be used to endorse or promote products derived from this software without
+   specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+## vis-network 9.1.2
+
+Copyright (c) 2011-2017 Almende B.V.
+Copyright (c) 2017-2019 visjs contributors.
+
+vis-network is dual licensed under Apache-2.0 and MIT. The AAC renderer uses
+these assets under Apache-2.0; the full license accompanies this distribution
+in LICENSE. The original dual-license notice remains in the generated HTML.
+Source: https://visjs.github.io/vis-network/

{aac_cli-0.2.3 → 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.3"
+__version__ = "0.2.5"

aac_cli-0.2.5/aac_cli/_aeg/__init__.py

@@ -0,0 +1,4 @@
+"""Agent Execution Graph readers, token model and self-contained renderers.
+
+Import as aac_aeg. Hosted database adapters are supplied by the host application.
+The model and renderers are shared by local commands and hosted consumers."""

aac_cli-0.2.5/aac_cli/_aeg/cli.py

@@ -0,0 +1,293 @@
+"""Public local renderer and run discovery; online access uses only aac CLI JSON."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+import tempfile
+from collections.abc import Callable
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+from .inputs import (
+    InputError,
+    read_actions,
+    read_events,
+    read_json,
+    read_trace,
+    roots_and_mapping,
+    select_events,
+    token_id,
+    unjoinable_diagnostics,
+)
+from .model import extract_token_relation_graph
+from .visualizer import build_visual_aeg, write_html_aeg
+
+Query = Callable[[str, str], tuple[str, list]]
+
+
+def parser(
+    *, prog: str = "aeg", version_text: str = "shared AAC renderer"
+) -> argparse.ArgumentParser:
+    result = argparse.ArgumentParser(
+        prog=prog,
+        description="Explore observed authority and business evidence. Local inputs are never uploaded.",
+    )
+    result.add_argument("--version", action="version", version=version_text)
+    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."
+    )
+    for command in (render, listing):
+        command.add_argument(
+            "--events",
+            type=Path,
+            action="append",
+            default=[],
+            metavar="FILE",
+            help="Sidecar JSONL file; repeat for each agent.",
+        )
+        command.add_argument(
+            "--actions",
+            type=Path,
+            action="append",
+            default=[],
+            metavar="FILE",
+            help="Application action_taken JSONL file; repeat as needed.",
+        )
+    source = render.add_mutually_exclusive_group()
+    source.add_argument(
+        "--profile", help="Query this existing AAC CLI profile for authorized central metadata."
+    )
+    source.add_argument(
+        "--trace-json",
+        type=Path,
+        metavar="FILE",
+        help="Read a saved chain-show JSON export offline.",
+    )
+    selector = render.add_mutually_exclusive_group()
+    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.")
+    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(
+        "--from", dest="from_time", help="Inclusive ISO 8601 observation time with timezone."
+    )
+    listing.add_argument(
+        "--to", dest="to_time", help="Exclusive ISO 8601 observation time with timezone."
+    )
+    listing.add_argument("--output", choices=("table", "json"), default="table")
+    return result
+
+
+def _query(profile: str, root: str):
+    raise InputError("online rendering requires the aeg command supplied by aac-cli")
+
+
+def _render(args, events, query: Query) -> int:
+    if args.profile is not None and not args.profile.strip():
+        raise InputError("--profile must name an existing AAC CLI profile")
+    if not (args.events or args.actions or args.profile or args.trace_json):
+        raise InputError(
+            "supply --events, --actions, --trace-json or --profile; a root ID is a selector, not evidence"
+        )
+    root = args.root_token_id
+    if args.mint_response:
+        response = read_json(args.mint_response)
+        if not isinstance(response, dict):
+            raise InputError(f"{args.mint_response}: expected successful mint-response JSON object")
+        root = token_id(response.get("root_token_id"), str(args.mint_response))
+    if root is not None:
+        root = token_id(root, "--root-token-id")
+    trace_root = None
+    if args.trace_json:
+        trace_root, trace_events = read_trace(read_json(args.trace_json), str(args.trace_json))
+        events.extend(trace_events)
+        if root and root != trace_root:
+            raise InputError("selected root does not match --trace-json root_token_id")
+    if root is None:
+        roots, _ = roots_and_mapping(events)
+        if trace_root:
+            root = trace_root
+        elif len(roots) == 1:
+            root = next(iter(roots))
+        else:
+            raise InputError(
+                "cannot select one root; use local list then --root-token-id or --mint-response (never selects latest)"
+            )
+        print(f"Selected root: {root}", file=sys.stderr)
+    central_status = "not requested (offline)"
+    query_failed = False
+    if args.profile:
+        try:
+            queried_root, central = query(args.profile, root)
+            if queried_root != root:
+                raise InputError("central response root does not match selected root")
+            events.extend(central)
+            central_status = "available; best-effort metadata, not a complete execution record"
+        except InputError as exc:
+            query_failed = True
+            central_status = str(exc)
+            print(central_status, file=sys.stderr)
+    elif args.trace_json:
+        central_status = f"saved trace: {args.trace_json}; offline metadata export"
+    selected, diagnostics = select_events(events, root)
+    graph = extract_token_relation_graph(selected)
+    if not graph.tokens:
+        raise InputError(
+            "no reconstructable token observations for the selected root; supply sidecar evidence or an available central trace"
+        )
+    graph.diagnostics.extend(diagnostics)
+    graph.diagnostics.extend(
+        [
+            f"Selected root: {root}",
+            f"Central evidence: {central_status}",
+            "Partial evidence: only supplied observations are shown. Missing participants, ancestors, fields and outcomes are not success or failure.",
+            "Central metadata intentionally omits private business details, authority caps, exact expiry and full receipts. Forwarding may also omit or delay events.",
+            "Application records are reports, not verified business truth. A mint/receive success does not prove business completion. Receipt verdicts are observations, not re-verification by this tool.",
+            "Distinct action records are retained; these formats do not establish exactly-once business-action counts.",
+        ]
+    )
+    protected = [
+        *args.events,
+        *args.actions,
+        *([args.trace_json] if args.trace_json else []),
+        *([args.mint_response] if args.mint_response else []),
+    ]
+    if args.output.resolve() in {path.resolve() for path in protected}:
+        raise InputError("--output must not overwrite an evidence input")
+    visual = build_visual_aeg(graph)
+    with tempfile.TemporaryDirectory(prefix="aac-aeg-") as directory:
+        rendered = write_html_aeg(visual, root, out_dir=Path(directory))
+        args.output.parent.mkdir(parents=True, exist_ok=True)
+        args.output.write_text(rendered.read_text(encoding="utf-8"), encoding="utf-8")
+    for diagnostic in diagnostics:
+        print(diagnostic, file=sys.stderr)
+    print(
+        f"AEG written to {args.output} ({len(graph.tokens)} observed/referenced tokens; partial evidence)",
+        file=sys.stderr,
+    )
+    return 4 if query_failed else 0
+
+
+def _date(value: str) -> datetime:
+    try:
+        parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
+        if parsed.tzinfo is None:
+            raise ValueError("timezone required")
+        return parsed.astimezone(timezone.utc)
+    except ValueError as exc:
+        raise InputError(f"invalid time {value!r}; use ISO 8601 with timezone") from exc
+
+
+def _list(args, events) -> int:
+    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"
+        )
+    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:
+        match = re.fullmatch(r"([1-9][0-9]*)([mhd])", args.since)
+        if not match:
+            raise InputError("--since requires a positive duration such as 30m, 24h or 7d")
+        try:
+            start = datetime.now(timezone.utc) - timedelta(
+                seconds=int(match[1]) * {"m": 60, "h": 3600, "d": 86400}[match[2]]
+            )
+        except OverflowError as exc:
+            raise InputError("--since duration is outside supported range") from exc
+    if start and stop and start > stop:
+        raise InputError("--from/--since must precede --to")
+    roots, mapping = roots_and_mapping(events)
+    diagnostics = [
+        f"{e.raw_event.get('_source', e.source)}: unmatched action {e.token_id}; supply sidecar root mapping"
+        for e in events
+        if e.event_type == "action_taken" and e.token_id not in mapping
+    ]
+    rows = []
+    diagnostics.extend(unjoinable_diagnostics(events))
+    for root in sorted(roots):
+        observed = [
+            e
+            for e in events
+            if e.root_token_id == root
+            or (e.event_type == "action_taken" and mapping.get(e.token_id) == root)
+        ]
+        task_refs = sorted(
+            {
+                str(
+                    e.raw_event.get("task_ref")
+                    or (e.raw_event.get("action_payload") or {}).get("task_ref")
+                )
+                for e in observed
+                if e.raw_event.get("task_ref")
+                or (e.raw_event.get("action_payload") or {}).get("task_ref")
+            }
+        )
+        if args.task_ref and args.task_ref not in task_refs:
+            continue
+        observed = [
+            e
+            for e in observed
+            if (start is None or _date(e.timestamp_iso) >= start)
+            and (stop is None or _date(e.timestamp_iso) < stop)
+        ]
+        if not observed:
+            continue
+        times = sorted(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],
+                "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))
+    else:
+        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"
+            )
+    for diagnostic in diagnostics:
+        print(diagnostic, file=sys.stderr)
+    return 0
+
+
+def main(
+    argv: list[str] | None = None,
+    *,
+    query: Query | None = None,
+    prog: str = "aeg",
+    version_text: str = "shared AAC renderer",
+) -> int:
+    args = parser(prog=prog, version_text=version_text).parse_args(argv)
+    events = []
+    try:
+        events = read_events(args.events) + read_actions(args.actions)
+        return (
+            _render(args, events, query or _query)
+            if args.command == "render"
+            else _list(args, events)
+        )
+    except (InputError, ValueError, OSError) as exc:
+        for diagnostic in unjoinable_diagnostics(events):
+            print(diagnostic, file=sys.stderr)
+        print(f"{prog}: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())