agentframe-py 0.1.0__tar.gz → 0.3.0__tar.gz

agentframe_py-0.3.0/.github/workflows/base-image.yml

@@ -0,0 +1,62 @@
+# Weekly check that the python:3.13-slim digest pinned by `agentframe compose`
+# (src/agentframe/compose.py, tests/unit/golden/Dockerfile and
+# docs/guides/development.md) is still the tag's current digest. When it is
+# not, it opens one issue and fails, so a maintainer refreshes the pin
+# deliberately; it never writes to the repository.
+name: Base image digest
+
+on:
+  schedule:
+    - cron: "0 6 * * 1"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      issues: write
+    env:
+      IMAGE: python
+      TAG: 3.13-slim
+      ISSUE_TITLE: Refresh the pinned python:3.13-slim digest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Compare the pinned and current digests
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          pinned=$(sed -n 's/^FROM .*@//p' tests/unit/golden/Dockerfile)
+          token=$(curl -fsS "https://auth.docker.io/token?service=registry.docker.io&scope=repository:library/${IMAGE}:pull" | jq -r .token)
+          current=$(curl -fsSI \
+            -H "Authorization: Bearer ${token}" \
+            -H "Accept: application/vnd.oci.image.index.v1+json" \
+            -H "Accept: application/vnd.docker.distribution.manifest.list.v2+json" \
+            "https://registry-1.docker.io/v2/library/${IMAGE}/manifests/${TAG}" \
+            | tr -d '\r' | sed -n 's/^docker-content-digest: //Ip')
+          if [[ ! "${current}" =~ ^sha256:[0-9a-f]{64}$ ]]; then
+            echo "::error::Could not read the current ${IMAGE}:${TAG} digest."
+            exit 1
+          fi
+          echo "Pinned:  ${pinned}"
+          echo "Current: ${current}"
+          if [[ "${pinned}" == "${current}" ]]; then
+            exit 0
+          fi
+          open=$(gh issue list --state open --search "\"${ISSUE_TITLE}\" in:title" --json number --jq length)
+          if [[ "${open}" == "0" ]]; then
+            gh issue create --title "${ISSUE_TITLE}" --body "$(cat <<EOF
+          \`${IMAGE}:${TAG}\` now resolves to \`${current}\`; \`agentframe compose\` pins \`${pinned}\`.
+
+          After testing the new image, update the digest in \`src/agentframe/compose.py\` (\`BASE_IMAGE\`), \`tests/unit/golden/Dockerfile\` and \`docs/guides/development.md\`. See the Containers section of the development guide.
+
+          Opened by the [Base image digest workflow](${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}).
+          EOF
+          )"
+          fi
+          echo "::error::${IMAGE}:${TAG} moved to ${current}; refresh the pinned digest."
+          exit 1

{agentframe_py-0.1.0 → agentframe_py-0.3.0}/AGENTS.md

@@ -12,13 +12,17 @@ release (M8+), not an optional add-on or a hosting platform.
 
 This repository contains the M0 development tooling, M1 model-free
 authoring/local `Runtime`, M2 native A2A hosting, M3 Ollama/Foundry text
-generation, M4 typed structured outputs, M5 bounded tool calling and M6 built-in
-opt-in model routing alongside design documentation. There
-is no published package or stable API, and later-milestone features are not
-implemented. Keep design API examples beyond the implemented surface labeled
-as unimplemented; explicitly approved names/defaults
-are decisions, not still-unresolved recommendations. Do not scaffold implementation or
-add dependencies merely to make design snippets executable.
+generation, M4 typed structured outputs, M5 bounded tool calling, M6 built-in
+opt-in model routing and M7 hardening alongside design documentation. Version
+0.1.0, the first usable single-agent release, and version 0.2.0, the M8+
+multi-agent release (#83-#97), are published on PyPI as `agentframe-py`
+(import `agentframe`). Pre-1.0 there is no stable API. M9 evaluation (#164, #152-#163)
+and M10 model-planned orchestration (#177, #166-#176) are complete and form
+version 0.3.0; later features (MCP, telemetry, streaming) are not implemented. Keep design API examples beyond
+the implemented surface labeled as unimplemented; explicitly approved
+names/defaults are decisions, not still-unresolved recommendations. Do not
+scaffold implementation or add dependencies merely to make design snippets
+executable.
 
 ## Code quality and readability
 
@@ -85,23 +89,27 @@ Folders stay one level deep. Put new code in the group that owns the concept:
 | Path | Contents |
 | --- | --- |
 | `src/agentframe/__init__.py` | Public API re-exports; every public name is importable from `agentframe`. |
-| `src/agentframe/` (root) | `errors.py`, `testing.py` (`ScriptedModel`), `cli.py` (`agentframe run`). |
+| `src/agentframe/` (root) | `errors.py`, `testing.py` (`ScriptedModel`), `cli.py` (`agentframe run` / `dev` / `compose` / `eval`), `project.py` (`agentframe.yaml`), `dev.py` (`dev_settings()`), `dev_server.py` (`agentframe dev` supervisor), `compose.py` (`agentframe compose` generator). |
 | `src/agentframe/authoring/` | `Agent`, `@agent` / `@skill`, definitions, `RunContext`, `Inject` / `Services`. |
 | `src/agentframe/runtime/` | `Runtime`, generation, `RunLimits`, `RunOptions`, `Usage`. |
 | `src/agentframe/models/` | `base.py` model protocol and settings; provider adapters `ollama.py`, `foundry.py`; `strict_schema.py` (OpenAI strict JSON-schema converter). |
 | `src/agentframe/hosting/` | `AgentApp`, `HostConfig`, Agent Card, A2A executor, routing. |
 | `src/agentframe/security/` | `Principal`, authentication, authorization. |
+| `src/agentframe/orchestration/` | `RemoteSkill`, `SkillCatalog`, bounding of untrusted card text, `RemoteTool` (remote entries as model tools, with per-entry permissions and tool checks), `Plan` / `PlanStep` with static checks and reference substitution (`plan.py`), the `ctx.plan` planning call (`planning.py`) and the plan executor behind `ctx.run_plan` (`execution.py`, `PlanResult`, `StepResult`) (M10). |
+| `src/agentframe/discovery/` | `AgentRegistry`, `AgentReference`, `AgentQuery`, file and environment registries (M8+). |
+| `src/agentframe/evaluation/` | Evaluation harness (M9): `cases.py` (`Case`, `load_cases`), `targets.py` (`Target`, `TargetResult`, `LocalSkill`, `A2ATarget`), `scoring.py` (`Score`, scorer calls, built-ins `equals`, `contains`, `valid`), `judge.py` (`Judge`, the rubric scorer's model-backed run and its budget holds), `report.py` (`CaseResult`, `EvalReport`, versioned JSON, `require`), `budget.py` (`TokenBudget`, evaluation-wide token holds), `harness.py` (`Evaluation`). Imported as `agentframe.evaluation`, not re-exported from `agentframe`, so its `__init__.py` re-exports its own public names. |
 | `tests/unit/<group>/` | Unit tests mirroring the source groups; root-module tests in `tests/unit/`. |
 | `tests/integration/` | Interoperability, real providers, success criterion, README example. |
-| `tests/support/` | Shared helpers, on pytest's `pythonpath` (`from local_server import ...`). |
-| `examples/` | Runnable examples, each with `create_app()`; `smoke.py` checks them all against the installed wheel in CI. |
+| `tests/support/` | Shared helpers, on pytest's `pythonpath` (`from local_server import ...`); `agent_processes.py` starts agents (`agentframe run`) and the plain A2A peer (`peer_process.py`) as separate processes for release tests. |
+| `examples/` | Runnable examples, each with `create_app()` (`evaluation.py` has `create_evaluation()` instead; `multi_agent/planner_evaluation.py` has `create_planner_evaluation(model, runtime)`); `smoke.py` checks them all against the installed wheel in CI. `multi_agent/` holds the research, writer and planner agents (hand-written `plan`, model-planned `propose` / `planned`, M10). |
 | `docs/roadmap.md` | Product boundaries, decisions and milestones. |
 | `docs/guides/` | How to use AgentFrame and how its behavior works. |
 | `docs/design/` | Rationale and proposed designs. |
 | `docs/api/` | Public surface reference. |
 
 Keep subpackage `__init__.py` files to a short docstring; add public exports to
-the top-level `__init__.py` only. Import internal modules by full path, for
+the top-level `__init__.py` only (except `agentframe.evaluation`, which
+`import agentframe` must not load). Import internal modules by full path, for
 example `from agentframe.runtime.limits import RunLimits`. Keep test basenames
 unique, since test folders are not packages.
 
@@ -114,7 +122,20 @@ clear error for an unknown model/deployment, a hosted structured call through
 the official A2A client, a validated typed `output=` result and the example's
 `summarize` skill returning a typed data part over A2A, a one-tool round trip
 run locally and through `examples/orders.py` over A2A (skipped if the model
-lacks tool support), a Foundry one-tool round trip that replays encrypted
+lacks tool support), a model calling a localhost agent's skill as a remote
+tool (M10 #167, checking only that the entry was called; skipped without tool
+support), a rubric `Judge` grading one model-free case in an `Evaluation`
+by majority of `votes=3` (M9 #160, #161), `examples/evaluation.py`'s answers
+graded by a rubric judge (M9 #163; xfails for Ollama when the small judge
+fails correct answers), a model planning one unambiguous
+two-step goal over two localhost agents' cards with `ctx.plan` (M10 #170,
+checking only the entries and the dependency; `llama3.2:3b` often writes
+an invalid or different plan, an Ollama xfail), the `examples/multi_agent` planner planning and running its
+post with the real model and the planner evaluation with `report.require`
+(M10 #176, `-k real_planner`; specialists use stand-in models; for Ollama only
+model-quality outcomes xfail: an invalid or empty plan, a plan the example's
+checks refuse, or more than half the evaluation's plans erroring that way;
+any other failure fails), a Foundry one-tool round trip that replays encrypted
 reasoning items and one unambiguous free-text request routed by
 `examples/routed_assistant.py` over A2A (checking only the selected skill and
 that its argument is present, since routing is nondeterministic). They are marked
@@ -145,6 +166,20 @@ AGENTFRAME_TEST_FOUNDRY=1 AGENTFRAME_FOUNDRY_ENDPOINT=<base-url> \
 
 An enabled provider with a missing required variable fails rather than skips.
 
+`tests/integration/test_foundry_agents.py` has opt-in `foundry` tests for
+`FoundryAgentRegistry` (#86): it lists a real project with one A2A-enabled
+agent and fetches that agent's card, read-only. It runs only with
+`AGENTFRAME_TEST_FOUNDRY_AGENTS=1`, `AGENTFRAME_FOUNDRY_PROJECT_ENDPOINT`
+(`https://<account>.services.ai.azure.com/api/projects/<project>`) and
+`AGENTFRAME_FOUNDRY_A2A_AGENT` (the agent's name), after `az login`. Setup and
+roles are in `docs/api/discovery.md#foundryagentregistry`. The same agent is the
+real non-AgentFrame server for #94: one test `ask`s it once, another checks
+`call` is refused before sending. In CI, `test_multi_agent_interop.py` proves
+both directions against a plain SDK peer (`tests/support/a2a_peer.py`). For
+#159 the same file evaluates the agent with one `A2ATarget` `ask` case and
+checks a `skill=` case is refused before sending; `test_evaluation_interop.py`
+does the same against the plain SDK peer in CI.
+
 `tests/integration/test_entra_interoperability.py` has one opt-in `entra` test
 using a real token from `az account get-access-token`, enabled with
 `AGENTFRAME_TEST_ENTRA=1`, `AGENTFRAME_ENTRA_TENANT_ID` and
@@ -248,6 +283,20 @@ downgrade to prompts. Implemented wire format (M2 #5): activate the card's
 skill-call URI via `A2A-Extensions` (echoed in the response), skill ID in message
 metadata `agentframe.skill`, exactly one JSON-object data part; malformed ->
 JSON-RPC InvalidParams, no task. Not a standard A2A `skill` field.
+Implemented (#89): the same URI carries caller context; an activated message
+without `agentframe.skill` is free text. Cards list `params.context`
+(`deadline_ms`, `hops`, `max_total_tokens` since #90); senders send only
+listed fields (0.1.0 lists none).
+Receiver timeout = min(own, `agentframe.deadline_ms`); `RunContext.hops`;
+`RunLimits.max_remote_hops=5`: caller fails before sending, deeper request
+REJECTED with base `LimitExceededError` message; depth is cooperative.
+Implemented (#91): context fields `root_invocation_id`/`parent_invocation_id`
+(lowercase UUID strings; invalid -> ignored, new root, never echoed or an
+error). Hosted runs log `Run started`/`Run completed` (INFO) with `extra`
+`agent`, `invocation_id`, `root_invocation_id`, `parent_invocation_id`; no
+log format set; root not exposed on `RunContext`. Valid W3C `traceparent`
+(version 00) plus valid `tracestate` forwarded unchanged as headers to every
+peer, invalid dropped; no spans or trace IDs created. Never authentication.
 Free-text/extension-unaware callers use custom or opt-in model routing plus
 validated extraction. Ambiguity/missing arguments asks back through
 `TASK_STATE_INPUT_REQUIRED`, never guesses; the caller answers in the same task,
@@ -400,9 +449,11 @@ call specialists over A2A, not a workflow/graph engine.
 `AgentRegistry` is a small read-only abstract base with proposed async
 `get(agent_id) -> AgentReference` and `list(query: AgentQuery) ->
 list[AgentReference]`; pagination is unresolved. Environment/file adapters read
-explicit sources. `FileAgentRegistry("agents.yaml")` reads a YAML name+URL list
-(detailed keys/schema open); `EnvironmentAgentRegistry("AGENTFRAME_AGENTS")`
-uses an explicit variable (payload encoding open).
+explicit sources. Implemented (#83): `AgentReference(name, card_url)` (the Agent
+Card URL), `AgentQuery(names=...)`; `FileAgentRegistry("agents.yaml")` reads a
+YAML `name`/`url` list on each call (1 MiB, `safe_load`, PyYAML core dep);
+`EnvironmentAgentRegistry("AGENTFRAME_AGENTS")` reads comma-separated
+`name=url` pairs. Config problems and unknown names raise `DefinitionError`.
 `FoundryAgentRegistry` uses the chosen Foundry project agents API through
 `azure-ai-projects` 2.x (2.10.0 observed), project endpoint
 `https://{account}.services.ai.azure.com/api/projects/{project}`. Incoming A2A
@@ -416,15 +467,28 @@ Foundry A2A connections are a possible additional reference source, not decided.
 Model deployments are not agent endpoints; no AgentFrame-to-Foundry deployment
 or tested registry integration is claimed.
 
-Separate `AgentCardResolver` and library-managed `AgentDirectory` own native SDK
-card fetch/validation/cache/refresh and owned-resource lifecycle, not
-per-backend user HTTP loops. No import/construction I/O or implicit polling;
-background refresh is opt-in. Cache TTL defaults to 300 seconds; automatically
-refresh on stale access, failing unless `allow_stale=True` explicitly.
+Implemented (#84): `AgentDirectory(sources=[...], card_ttl_seconds=300,
+allow_stale=False, allow_http_hosts=(), http_client=None,
+max_reply_bytes=8 MiB)` (#150: `Remote` replies streamed, over it -> safe
+`RemoteAgentError`) owns SDK card
+fetch/validation/cache/refresh via an internal fetcher (no public
+`AgentCardResolver`/`CardCacheConfig`). Sources read on every `get`; cards
+cached per card URL, refetched when stale; failed refresh raises unless
+`allow_stale=True` (`DiscoveredAgent.stale`, warning). https only except
+loopback/`allow_http_hosts`, no redirects, 10 s, 1 MiB, interface URL same
+origin as the registry `card_url`; no caller credentials. Remote failures
+raise `RemoteAgentError`; duplicate names across sources `DefinitionError`.
+No construction I/O or background tasks; closes only its own client.
 Compose `AgentDirectory(sources=[...])`, inject via `AgentApp(directory=...)`,
-and validate configured `Remote["name"]` bindings at startup.
+and validate configured `Remote[Literal["name"]]` bindings at startup.
 `directory.find(skill="find_sources")` / `find(tags=["research"])` returns
 matching native cards from bounded validated enrichment, not assumed reference fields.
+Implemented (#85): `find(*, skill=None, tags=())`, at least one filter; skill
+ID and all-of tags must match on the same card skill; every source listed,
+cards resolved through the cache, at most 8 fetches at a time; any source/card
+failure raises (honouring `allow_stale`); source order; no pagination (small
+curated sources). Found cards are not callable; orchestrators call configured
+remotes, dynamic invocation is deferred.
 Inject directories as application dependencies;
 caller-owned resources stay caller-owned unless explicitly transferred. No
 registration writes, deploy/start/stop/delete, leases/federation, or A2A task
@@ -440,11 +504,47 @@ references/cards/source files; enforce application-selected outbound auth and
 destination/redirect policy, bounded reads/deadlines/cancellation and safe
 telemetry. Discovery does not delegate or auto-expose skills as tools. A separate
 `RemoteAgentClient` may remain underlying/explicit client with construction open.
-Author skills use `Remote["name"]` (excluded from external schemas),
+Author skills use `Remote[Literal["name"]]` (excluded from external schemas),
 `call("skill", ..., output=list[Source], max_total_tokens=...)` for structured
 A2A, or `ask(text)` for any compatible peer. Both wait within caller deadline;
 remote input-required raises `ClarificationNeededError` with question, no
-automatic back-and-forth. See `docs/design/discovery.md` and `docs/api/discovery.md`.
+automatic back-and-forth. Implemented (#87): `class Remote[N: str]` read from the
+`Literal` (alias `type Research = Remote[Literal["research-agent"]]`; string form
+fails mypy), `Runtime(directory=)`/`AgentApp(directory=)` (app-owned; no
+directory -> construction `DefinitionError`), `Runtime.validate_remotes` at
+startup, bound per run inside its deadline. `ask` sends via the SDK
+`JsonRpcTransport` with the directory client to `interface_url` only,
+`return_immediately` then `GetTask` polling (0.25 s -> 1 s), per-request
+`A2A-Version`/timeout headers; deadline or cancellation sends best-effort
+`CancelTask`.
+Implemented (#88): `call(skill, /, *, output=None, **arguments)` checks the
+card declares the skill-call extension and skill (else `RemoteAgentError`, no
+send, no `ask` fallback), sends the M2 wire format with per-request
+`A2A-Extensions`, reuses `ask`'s wait/cancel, decodes text or `{"value": ...}`
+and validates `output` (`OutputValidationError`, no remote data).
+Implemented (#90): `ask`/`call` take `max_total_tokens=` (default: all the run
+has left), held atomically in the run's `RunAccounting` before sending and sent
+as `agentframe.max_total_tokens` only to peers listing it in `params.context`
+(older receivers reject unknown keys). Receiver uses min(own, incoming). The
+task's usage snapshot `total_tokens` replaces the hold, even if higher;
+non-advertising peers hold nothing and make usage unknown (`None`). Over the
+remaining budget -> `TokenLimitExceededError` before sending (default-ceiling
+message says to pass `max_total_tokens` per call for fan-out).
+Implemented (#92): `remotes={name: Service(credential=...)}` on
+`Runtime`/`AgentApp` (same rule as `services=`); `OutboundCredential` protocol
+`async headers()` + `satisfies(scheme)`, built-ins `APIKeyCredential(key,
+header="X-API-Key")`, `EntraAppCredential(credential, scope=...)`. Headers per
+request (send, polls, cancel) to `interface_url` only; no redirects. Startup:
+card security must be met by the entry, else `DefinitionError`; open cards need
+none. Implemented (#93): `OnBehalfOf(scope=...)` entries; credential on
+inbound `EntraIDAuth(client_id=audience, client_credential=secret|cert bytes|
+assertion func)`; delegated tokens (`scp`, not `idtyp=app`) kept privately as
+`VerifiedCaller.user_assertion`; one azure `OnBehalfOfCredential` per run.
+Non-Entra host/no credential -> startup `DefinitionError`; no user (app-only,
+local run) -> `PermissionDeniedError`; failed exchange -> `AuthenticationError`;
+never a `Service` fallback. Opt-in `entra` OBO test uses two registrations.
+`ClarificationNeededError(question, task_id, context_id)` fails a hosted
+orchestrator task. See `docs/design/discovery.md` and `docs/api/discovery.md`.
 
 Plan cross-hop verified identity/delegation without authority amplification,
 permissions, deadlines, remaining token allowance and trace/correlation;
@@ -460,18 +560,41 @@ reservations. Default max 5 remote hops, excess fails. These controls use the
 same A2A extension; detailed config/wire/usage trust remains open, not base
 protocol fields or hard billing guarantees.
 No orchestration helpers in the first multi-agent release: plain await,
-asyncio.TaskGroup and directory.find. Later optional `Remote[ResearchAgent]`
+asyncio.TaskGroup and directory.find. M10 (0.3.0) adds opt-in remote skills as model
+tools and checked plans (`docs/guides/orchestration.md`); plain await stays
+the default. Later optional `Remote[ResearchAgent]`
 typed proxy always uses structured selection, never prompt routing. Prove two or more
 independently deployed AgentFrame agents, an orchestrator discovering/calling a
 specialist with propagated context, and non-AgentFrame A2A client/server interop.
 Development support starts with running N agents locally, then container
 packaging; Foundry/Kubernetes templates are later. M2 `agentframe run module:create_app`
 serves the app's own configured `AgentApp` (`--dev module:Class` is localhost-only
-anonymous; Uvicorn is the `server` extra). M8+ `agentframe dev` reads agentframe.yaml (names/modules/ports),
-starts localhost agents, writes local registry, configures dev API keys and
-combines logs tagged by agent/invocation. One container per agent; Dockerfile
-template and generated docker-compose example. Exact schema/generation/key
-lifecycle remains open; no actual config files before implementation.
+anonymous; Uvicorn is the `server` extra). Implemented (#95): `agentframe dev`
+reads agentframe.yaml (`agents: {name: {app: module:create_app, port}}`,
+`project.py`), starts each as `python -m agentframe run` on 127.0.0.1 in file
+order after the previous `/ready`, writes `.agentframe/agents.yaml` (name/url
+only, self-gitignored), generates one random key per agent per session (an
+agent calls others with its own key, verified as its name), passes keys only
+via child env (`AGENTFRAME_DEV`, `AGENTFRAME_PUBLIC_URL`,
+`AGENTFRAME_DEV_REGISTRY`, `AGENTFRAME_DEV_API_KEYS`,
+`AGENTFRAME_DEV_REMOTE_KEYS`), never disk/logs; optional
+`AGENTFRAME_DEV_CLIENT_KEY` is caller `developer`. Factories call
+`dev_settings()` (refuses without `AGENTFRAME_DEV=1`; directory has its own
+http client; reads `AGENTFRAME_ALLOW_HTTP_HOSTS`). Output prefixed
+`[agent-name]`, agents log INFO; failures stop all and exit 1; Ctrl+C sends
+one SIGTERM (children in own session), kills after 35 s; a client key with
+`,`/`=` is refused. Implemented (#96): `agentframe compose [--config]
+[--force]` (`compose.py`) writes development `compose.yaml` (one service per
+agent, `agentframe run APP --host 0.0.0.0 --port P`, `127.0.0.1:P:P`, `/ready`
+healthcheck, depends on earlier agents healthy; env = dev contract with
+`AGENTFRAME_PUBLIC_URL=http://name:P`, `AGENTFRAME_AGENTS` (read by
+`dev_settings()` as an `EnvironmentAgentRegistry`), `AGENTFRAME_DEV=1`,
+`AGENTFRAME_ALLOW_HTTP_HOSTS`=service names; keys only
+`${NAME_API_KEY:?...}`/`${AGENTFRAME_DEV_CLIENT_KEY:?...}` from user `.env`)
+and, only if missing, a `Dockerfile` (digest-pinned `python:3.13-slim`,
+`dist/*.whl`, `USER 10001:10001`); `--force` overwrites only `compose.yaml`.
+Golden files in `tests/unit/golden/`; opt-in `docker` test
+(`AGENTFRAME_TEST_DOCKER=1`, skipped without a running Docker).
 No hosting platform is implied. See `docs/guides/development.md`.
 
 ### Initial release boundaries
@@ -504,11 +627,19 @@ A2A failures use safe failed/rejected states as appropriate; no raw provider
 exception, stack trace or secret goes to callers. Log diagnostics with redaction:
 failed runs log ID, class and safe message; skill/tool/router tracebacks stay in
 operator logs with the ID, so authors keep secrets out of exception messages.
-`tests/integration/test_hardening.py` is the M7 end-to-end acceptance suite.
+`tests/integration/test_hardening.py` is the M7 end-to-end acceptance suite;
+`tests/integration/test_multi_agent_release.py` is M8+'s, running
+`examples/multi_agent` as separate `agentframe run` processes;
+`tests/integration/test_orchestration_release.py` is M10's (#176), running its
+research, writer and planner agents, the plain SDK peer and a registry-wide
+coordinator (`tests/support/release_targets.py`) as separate processes with a
+scripted planning model, plus the planner evaluation.
 Network host examples must include clearly labeled application-supplied
 development authentication/authorization placeholders where appropriate;
 loopback/omission is not access policy or a production-safe default.
-M8+ adds `ClarificationNeededError` under `AgentFrameError`; local client
+M8+ adds `RemoteAgentError` (#84; failures caused by another agent, optional
+`task_id`/`task_state`) and `ClarificationNeededError` under
+`AgentFrameError`; local client
 input-required question is not a failed remote task or durable resumption.
 
 Use explicit model selection, finite execution limits, validated inputs/outputs,
@@ -570,11 +701,12 @@ remain open; tracing/accounting/enforcement work independently. See
 
 Read `README.md` and `docs/README.md` first. Keep `docs/roadmap.md`, the
 guides (`docs/guides/annotations.md`, `agent-examples.md`, `limits.md`,
-`authorization.md`, `development.md`) and the design docs
+`authorization.md`, `development.md`, `evaluation.md`, `orchestration.md`) and the design docs
 (`docs/design/base-classes.md`, `tracing.md`, `mcp-skills.md`,
-`prompt-safeguarding.md`, `discovery.md`, `streaming.md`) consistent, including
-discovery/streaming API pages and navigation. Preserve the distinction between
-confirmed product direction and illustrative API details.
+`prompt-safeguarding.md`, `discovery.md`, `streaming.md`, `evaluation.md`,
+`orchestration.md`) consistent, including discovery/streaming API pages and
+navigation. Preserve the distinction between confirmed product direction and
+illustrative API details.
 
 Maintain `docs/api/README.md` and its linked surface reference pages alongside
 those design documents. Give every proposed decorator, class, and known public