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

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

@@ -12,13 +12,16 @@ 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, is published on PyPI as
+`agentframe-py` (import `agentframe`). Pre-1.0 there is no stable API. The
+M8+ multi-agent stories (#83-#97) are complete and form the 0.2.0
+multi-agent release; 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,12 +88,13 @@ 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`), `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/discovery/` | `AgentRegistry`, `AgentReference`, `AgentQuery`, file and environment registries (M8+). |
 | `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 ...`). |
@@ -145,6 +149,17 @@ 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`).
+
 `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 +263,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 +429,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 +447,26 @@ 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)` 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 +482,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;
@@ -467,11 +545,32 @@ 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 +603,15 @@ 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.
 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,
@@ -572,9 +675,10 @@ 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
 (`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

agentframe_py-0.2.0/CHANGELOG.md

@@ -0,0 +1,195 @@
+# Changelog
+
+All notable changes to AgentFrame are listed here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+Pre-1.0: public APIs may change in minor releases; changes are listed in the
+changelog.
+
+## [Unreleased]
+
+## [0.2.0] - 2026-11-14
+
+The multi-agent release (M8+): independently deployed AgentFrame agents find
+each other through registries and an `AgentDirectory`, and orchestrator skills
+call them over A2A with `Remote.call` and `Remote.ask`, carrying deadlines,
+token budgets, hop limits, correlation and caller identity across hops.
+`agentframe dev` and `agentframe compose` run several agents locally or in
+containers. Calls interoperate with non-AgentFrame A2A agents, including
+Microsoft Foundry agents.
+
+### Added
+
+- **Multi-agent (M8+):** `examples/multi_agent`, a planner orchestrator and a
+  research agent with an `agentframe.yaml`. The planner finds the research
+  agent with `directory.find`, then fans out a structured `call` and a
+  free-text `ask` per topic in one `asyncio.TaskGroup`, each with its own
+  `max_total_tokens`. The release acceptance test runs both as separate
+  `agentframe run` processes; the examples smoke runner checks the example.
+- **Multi-agent (M8+):** `agentframe compose` writes a development
+  `compose.yaml`, one container per agent of `agentframe.yaml`, and, if
+  missing, a `Dockerfile` template (`python:3.13-slim` pinned by digest,
+  non-root, installs the project's wheels from `dist/`). Services bind
+  `0.0.0.0` inside their container, publish on `127.0.0.1` only, check
+  `/ready` and get the `agentframe dev` environment with service-name URLs
+  and the explicit `AGENTFRAME_DEV=1` / `AGENTFRAME_ALLOW_HTTP_HOSTS` opt-in.
+  Keys appear only as `${VAR}` references to a `.env` file the user creates.
+  Existing files are never overwritten without `--force`, and a `Dockerfile`
+  never. `dev_settings()` now also reads an `AGENTFRAME_AGENTS` registry, and
+  `agentframe dev` refuses an `AGENTFRAME_DEV_CLIENT_KEY` containing `,` or
+  `=` without showing it.
+- **Multi-agent (M8+):** `agentframe dev` runs every agent listed in
+  `agentframe.yaml` (`agents: {name: {app: module:create_app, port: int}}`)
+  as its own `agentframe run` process on `127.0.0.1`, wired together. It
+  checks ports first, starts agents in file order once each is ready, writes
+  `.agentframe/agents.yaml` with local card URLs, and generates one random
+  API key per agent per session, passed only through the agents'
+  environment, never written or logged. Every agent also accepts an optional
+  `AGENTFRAME_DEV_CLIENT_KEY` as caller `developer`. Output is combined with
+  an `[agent-name]` prefix, with each run's invocation IDs. Failures stop
+  every agent and exit 1; Ctrl+C stops them gracefully. App factories read the
+  wiring with the new `dev_settings()`, which refuses to run without
+  `AGENTFRAME_DEV=1`. `python -m agentframe` now runs the command line.
+- **Multi-agent (M8+):** cross-agent token budgets. `Remote.ask` and
+  `Remote.call` take `max_total_tokens=` (default: everything the run has
+  left), held atomically against the run's `RunLimits.max_total_tokens`
+  before sending and sent as `agentframe.max_total_tokens` to peers whose
+  card lists it in `params.context` (now `deadline_ms`, `hops`,
+  `max_total_tokens`). Receivers use the smaller of it and their own limit.
+  The usage the peer's task reports is charged to the run once, so
+  `RunResult.usage` includes every hop; peers that do not list the field hold
+  nothing and leave usage unknown (`None`), never zero. A ceiling over what is
+  left raises `TokenLimitExceededError` before sending.
+- **Multi-agent (M8+):** `OnBehalfOf(scope=...)` in `remotes=` calls a remote
+  agent on behalf of the signed-in user through the Microsoft Entra
+  on-behalf-of flow; the incoming token is never forwarded. `EntraIDAuth`
+  gains `client_id=`, `client_credential=` and `token_transport=`, and keeps a
+  delegated user token privately as `VerifiedCaller.user_assertion`. Startup
+  refuses `OnBehalfOf` behind non-Entra hosts or without a client credential;
+  app-only callers and local runs fail with `PermissionDeniedError`, failed
+  exchanges with `AuthenticationError`, never falling back to `Service`. The
+  `entra` extra now pins `azure-identity==1.27.0` and `aiohttp==3.14.5`.
+- **Multi-agent (M8+):** cross-agent correlation. Hosted runs log `Run
+  started` / `Run completed` at `INFO`, and their log records carry `agent`,
+  `invocation_id`, `root_invocation_id` and `parent_invocation_id` in
+  `logging` `extra` (AgentFrame sets no format). `Remote.ask` and `call` send
+  `agentframe.root_invocation_id` and `agentframe.parent_invocation_id` to
+  peers whose card lists them in `params.context`, so every agent of one
+  request logs the same root. Values that are not lowercase UUID strings are
+  ignored (the run becomes a new root), never echoed or trusted. A valid W3C
+  `traceparent` (and valid `tracestate`) is forwarded unchanged to every peer;
+  invalid ones are dropped. None of it authenticates or grants access, and
+  task metadata is unchanged.
+- **Multi-agent (M8+):** `Remote.ask` sends the run's remaining time
+  (`agentframe.deadline_ms`) and depth (`agentframe.hops`) to peers whose card
+  lists them in the skill-call extension's new `params.context`; others get
+  plain A2A. Receivers cap their timeout by the caller's deadline and reject
+  requests deeper than the new `RunLimits.max_remote_hops` (default 5); a run
+  at that depth fails before sending. New `RunContext.hops`. With the
+  extension activated, a message without `agentframe.skill` is now free text
+  instead of an `InvalidParams` error.
+- **Discovery (M8+):** read-only `AgentRegistry` base with `AgentReference`
+  (agent name and Agent Card URL) and `AgentQuery` (name filter), plus
+  `FileAgentRegistry` (YAML `name`/`url` list) and `EnvironmentAgentRegistry`
+  (comma-separated `name=url` pairs). PyYAML is a new core dependency.
+- **Discovery (M8+):** `AgentDirectory(sources=[...])` returns
+  `DiscoveredAgent` results with validated official SDK Agent Cards, cached
+  for 300 seconds, with `allow_stale`, `refresh`, `allow_http_hosts` and an
+  optional caller-owned `http_client`. New `RemoteAgentError` for failures
+  caused by another agent. `httpx` is now an exactly pinned core dependency.
+- **Discovery (M8+):** `AgentDirectory.find(skill=..., tags=...)` returns the
+  Agent Cards of listed agents with a skill matching the ID and every tag,
+  in source order. It fetches at most eight cards at a time through the cache
+  and raises on any source or card failure instead of returning fewer cards.
+- **Discovery (M8+):** `FoundryAgentRegistry(project_endpoint=...,
+  credential=...)` lists a Foundry project's A2A-enabled agents, mapped to
+  their A2A 1.0 Agent Card URLs. New optional `AgentRegistry.card_headers`
+  lets a source send its own credentials with its card requests; Foundry
+  sends a bearer token from its credential. The `foundry` extra now pins
+  `azure-ai-projects==2.11.0`.
+- **Remote agents (M8+):** skills declare another A2A agent as a
+  `Remote[Literal["name"]]` parameter (excluded from arguments, the Agent Card
+  and schemas), found through `Runtime(directory=...)` or
+  `AgentApp(directory=...)`; server startup checks every name with
+  `Runtime.validate_remotes`. `await remote.ask(text)` sends plain A2A text and
+  returns the text answer within the run's deadline, cancelling the remote
+  task on deadline or cancellation. New `ClarificationNeededError` when the
+  remote agent asks a question.
+- **Remote agents (M8+):** `await remote.call("skill", output=Type, **arguments)`
+  runs a remote AgentFrame agent's skill by ID through the skill-call
+  extension and validates its result into `output` (`OutputValidationError`
+  on mismatch). A peer whose card lacks the extension or the skill raises
+  `RemoteAgentError` before anything is sent, with no free-text fallback.
+  `output` and `max_total_tokens` cannot be remote argument names.
+- **Outbound identity (M8+):** `remotes={name: Service(credential=...)}` on
+  `Runtime` and `AgentApp` authenticates remote calls with the calling
+  agent's own identity: `APIKeyCredential(key, header="X-API-Key")` or
+  `EntraAppCredential(credential, scope=...)` (any `azure.core` async token
+  credential, sent as a bearer token), or any `OutboundCredential`.
+  Credentials go per request only to the card's validated interface origin,
+  never with redirects, and incoming caller credentials are never forwarded.
+  Agents whose card declares security, including Foundry A2A agents, can now
+  be called; startup fails with `DefinitionError` when the configured
+  credential cannot satisfy the card's security.
+
+### Fixed
+
+- `agentframe dev` no longer passes an exported `AGENTFRAME_AGENTS` to its
+  agents, which made `dev_settings()` list every agent twice and fail startup
+  with a duplicate-name `DefinitionError`.
+- URLs with a non-numeric or out-of-range port are refused as
+  `HostConfig.public_url` and registry card URLs.
+- `FileAgentRegistry` strips whitespace around names and URLs, like
+  `EnvironmentAgentRegistry`.
+- Credential headers (`Authorization`, `Proxy-Authorization`, `Cookie`,
+  `X-API-Key`) are dropped from the A2A SDK's call context after
+  authentication, so the SDK's debug logs no longer contain bearer tokens or
+  API keys.
+- `FoundryAgentRegistry` finds A2A-enabled agents again: the live Foundry API
+  lists them as `agent_endpoint.protocols: ["a2a", ...]`, which
+  `azure-ai-projects` 2.11.0 does not model, and its list response omits
+  `agent_endpoint` entirely, so every agent was skipped and lookups raised.
+  `list` now reads each queried agent's details (one call per agent), and the
+  `protocol_configuration.a2a` shape is still accepted.
+
+## [0.1.0] - 2026-11-13
+
+The first usable single-agent release, distributed on PyPI as `agentframe-py`
+and imported as `agentframe`.
+
+### Added
+
+- **Authoring:** `Agent` subclasses with `@agent` identity and one async
+  `@skill` method per advertised skill; Python types and Pydantic models as
+  validated input and output contracts; `Inject[T]` services registered with
+  `Services.add` / `add_scoped`; per-invocation `RunContext`.
+- **Local runtime:** `Runtime.invoke` returns a validated value and
+  `Runtime.run` a `RunResult` with invocation ID, usage, model and tool calls,
+  duration and finish reason. `RunLimits`, `ModelSettings` and `RunOptions`
+  resolve field by field from library to agent, skill and run.
+- **A2A 1.0 hosting:** `AgentApp` serves a generated native Agent Card and a
+  JSON-RPC endpoint through the official `a2a-sdk`. Structured requests name a
+  skill through the Agent Card's skill-call extension; free text uses a custom
+  `SkillRouter` or the opt-in `ModelRouter`, which asks back with
+  `TASK_STATE_INPUT_REQUIRED` when a request is ambiguous.
+  `agentframe run module:create_app` serves an application (`server` extra).
+- **Models:** `OllamaModel` (local Llama, `ollama` extra) and `FoundryModel`
+  (Microsoft Foundry GPT deployments, `foundry` extra), switched by
+  configuration only. One `ctx.generate` returns text, a validated Pydantic
+  instance with `output=`, or runs registered `@tool` functions with
+  `tools=[...]` within `max_tool_calls`. Refusal, truncation and unsupported
+  capabilities raise typed errors. `ScriptedModel` in `agentframe.testing`
+  scripts model replies for tests.
+- **Security:** `HostConfig(auth=...)` with `APIKeyAuth`, `EntraIDAuth`
+  (`entra` extra), explicit `AllowAnonymous` or a custom `Authenticator`;
+  skill `requires_permissions`, role mapping and an injected
+  `AuthorizationPolicy`, failing closed; optional `ExecutionPolicy` input,
+  model-request, tool and output checks.
+- **Hardening:** host ceilings for concurrent runs, request and response size,
+  and graceful shutdown; `/health` and `/ready`; A2A message deduplication by
+  caller and message ID; safe, correlated errors with redacted operator logs.
+- **Examples:** runnable examples in `examples/`, each checked against the
+  installed wheel by `python -m examples.smoke`.
+
+[0.2.0]: https://github.com/malcmiller/agentframe/releases/tag/v0.2.0
+[0.1.0]: https://github.com/malcmiller/agentframe/releases/tag/v0.1.0