req_managed_agents

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## v0.6.1 (2026-07-05)

### Changed
- Hygiene: removed internal issue-tracker identifiers and CI account/role
  identifiers from the public surface (a source comment, test annotations,
  and repo docs). No API or behavior change — the library surface is identical
  to v0.6.0; this release simply ships a clean latest.

## v0.6.0 (2026-07-04)

### Added
- **`ReqManagedAgents.Providers.Local`** — the third provider: the agent loop runs
  in-process (`:request_response`, one model call per turn) over a pluggable
  `chat_fun` with a neutral OpenAI-chat-completions-shaped wire contract
  (`chat_fun.(%{model:, messages:, tools:}) :: {:ok, response} | {:error, reason}`).
  Pointing the chat_fun at any OpenAI-compatible endpoint is a bare `Req.post` —
  including a gateway lane with a granted key for hard data-plane budget
  enforcement. Events are synthesized under the `local.*` namespace
  (`local.model_response`, `local.duplicate_tool_call`, `local.directive`);
  `provision/2` is identity. Limitation: `Providers.Local` is primarily scoped to
  `run/2` (one request per conn) — the final-turn directive counts polls across the
  conn's lifetime, so long-lived `start_link` sessions with many follow-ups may see
  it fire early on later requests.
- Local loop guards (relocated from biai-managed-agents `Core.Runner`, for
  weak-instruction-following local models): duplicate-call dedup (self-answered,
  never re-surfaced), consecutive-error corrective directives (≥2 per tool),
  final-turn directive (names the spec's `terminal_tool`), and transient-error
  retry with exponential backoff around the chat call (HTTP 408/≥500 + transport
  errors; `max_chat_retries`/`retry_backoff_ms`/`sleep_fun` opts).
- Optional `req_llm` dependency (`~> 1.10`, raise-at-first-use via
  `Local.Deps`) backing the default chat_fun; `model_config[:api_key]` and
  `[:base_url]` thread into the ReqLLM call.
- api_key carry-in: the Claude Managed Agents provider builds its client from
  `model_config: %{api_key:, base_url:}` when no `:client` is injected.
  (Bedrock AgentCore signs with SigV4 — not applicable.)
- Metadata carry-in: `model_config[:metadata]` merges into every telemetry
  event's metadata and into `SessionInfo.metadata` for `handle_event/3` —
  decision correlation (`mimir_request_id`, `decision_id`) rides uniformly
  across providers.

### Changed
- Positioning: "one Session loop, any loop host — server-side (Claude Managed
  Agents, AgentCore) or in-process (Local)". README, package description, and
  moduledocs updated; vocabulary and result shapes unchanged.

## v0.5.0 (2026-07-04)

### Added
- **`turn_guard`** — the between-turn governance hook, invoked after each turn's usage
  accumulation with `%{usage: %ReqManagedAgents.Usage{}, turns:, session_id:}`, returning
  `:cont` or `{:halt, reason}`. On halt the run stops with
  `{:error, {:halted, reason}}` and a `:terminated` `SessionResult` is notified. This
  contract is frozen: hosts compose policy (budget caps, grant checks) on top; RMA ships
  only the mechanism. Semantics: the guard runs *before* the `max_turns` check and wins
  when both would trip on the same turn; it fires on terminal-tool re-prompt turns (whose
  `turns` counter keeps incrementing); guards must not raise.
- Terminal-tool enforcement: `require_terminal_tool: true` + `terminal_tool: "name"` +
  `max_reprompts` (default 2). An `:end_turn` that never called the terminal tool is
  re-driven with a re-prompt; exhausted re-prompts finish with
  `stop_reason: :no_terminal_tool`. Re-prompt turns count against `:max_turns`.
- `rma.text_delta` — one documented synthetic event
  (`%{"type" => "rma.text_delta", "text" => chunk}`) emitted through `handle_event`
  alongside (never instead of) the raw event, on every provider that implements the new
  optional `Provider.text_delta/1`. Never stored in `SessionResult.events`.
- Outcomes (GH #31): `Event.define_outcome/3`, the `:outcome` Session option — a
  `%ReqManagedAgents.Outcome{}` struct or a map with the same atom keys — honored by
  the Claude Managed Agents kickoff (`user.define_outcome`; mutually exclusive with
  `:prompt`, outcome wins), optional `Provider.supports_outcomes?/0`
  (`{:error, :outcome_unsupported}` on Bedrock AgentCore), and terminal mapping for
  outcome stop reasons (`satisfied`/`max_iterations_reached` → `:end_turn`, `failed` →
  `:terminated`; `span.outcome_evaluation_end` with `needs_revision` is not terminal).
  Shape validation via `ReqManagedAgents.Outcome.new/1` (one gate shared by the start-time
  check and the kickoff): a non-nil `:outcome` that is not a valid struct or atom-keyed
  `%{description: binary, rubric: binary}` fails fast at start with
  `{:error, {:invalid_opts, :outcome}}` before provider-support is checked.
- `Session.send_event/2` — post a pre-built raw user event (e.g.
  `user.tool_confirmation`) into a running streaming session.

### Changed
- `TurnResult`/`SessionResult` `stop_reason` typespec widened to
  `String.t() | map() | atom() | nil` (`:no_terminal_tool`).

## v0.4.2 (2026-07-04)

### Changed
- Internal housekeeping: source comments and test names no longer reference
  internal tracker ids. No behavior, API, or documentation changes.

## v0.4.1 (2026-07-04)

### Fixed
- `Session.run/2` timeout now shuts down the in-flight poll task (Bedrock AgentCore
  invoke) and the streaming SSE consumer, so the client HTTP stream is torn down
  instead of continuing after the caller received `{:error, :timeout}`. Server-side
  execution may still run to the provider's own limit — on AgentCore, `timeoutSeconds`
  remains the authoritative server budget (Session moduledoc updated to match).

## v0.4.0 (2026-07-04)

### Added
- `ReqManagedAgents.Provisioner.Store` behaviour (`get/2`, `put/3`, `delete/2`,
  `delete_value/2`) — pluggable provision and tag storage. Two implementations: `Store.ETS`
  (default; in-process, unchanged semantics) and `Store.File` (JSON, `path:` required,
  atomic writes, single-writer assumption; handles and tags survive OS-process restarts for
  CLI/mix-task/cron consumers). `:store` option threads through `Provisioner.ensure/3`,
  `evict/2`, `ensure_environment/3`, `tag/4`, `resolve/2`, `prune_environments/3`, and
  the facade `provision/3` / `teardown/3`.
- `ReqManagedAgents.ensure_environment/3` (facade; delegates to `Provisioner.Environments`)
  — content-addressed, build-if-absent environment lifecycle. Provider-side name is
  `<base>_<digest8>`; a 409 recovers by name (same name = same image, always). Returned
  handle: `%{environment_id:, name:, digest:}`. Error taxonomy:
  `{:environment_archived, name}` (name exists but archived) /
  `{:environment_name_conflict, name}` (absent after 409 — unexpected provider state).
- `Provisioner.tag/4` — writes a movable `base:tag → digest` pointer to the configured
  store. `Provisioner.resolve/2` — resolves `"base:tag"` to a handle; never falls back;
  `{:error, :unknown_tag}` on miss; raises `ArgumentError` on a malformed ref (no colon).
- `Provisioner.prune_environments/3` — explicit image GC for a named base: archives
  versions beyond the newest `keep:` (REQUIRED, no default — deliberate friction for a
  permanent operation), always protecting tagged digests. Strict 8-hex suffix membership
  (a `"data"` prune never touches `"data_analysis"` images). Returns
  `{:ok, %{archived: [...], kept: [...]}}` or
  `{:error, {:partial, archived_so_far, {failed_name, reason}}}` on partial failure.
- Base-scoped digest index (`"digest:<base>:<digest8>"` store entries written at ensure
  time) so `resolve/2` can look up handles without a linear scan; the base scope prevents
  two bases sharing an identical spec from resolving each other's environments.
- `Provisioner.Runtimes`: `runtimes: [%{lang:, version:, via: :mise}]` on env specs
  participates in the spec digest automatically (a runtime change = a new image). When
  runtimes are declared, `ensure_environment/3` returns `bootstrap: %{script:, instructions:}`
  in the handle (derived on every call, never stored). `bootstrap_script/1` renders the
  mise install script; `system_prompt_block/1` renders the agent instruction. `required_hosts/1`
  feeds the allowlist merge into `networking.allowed_hosts` when networking is `:limited`.
  Spike-proven: ~11s end-to-end on ubuntu-24.04 (precompiled OTP via mise, no kerl compile).
  Only `via: :mise` is supported.

### Changed
- Provisioner cache keys namespaced: handles now stored under `"provision:" <> hash`
  (previously bare hash). Cache-only — existing entries are invisible to the new reader
  (re-provisions once per BEAM start on first upgrade); no consumer API impact.
- Facade `teardown/3` forwards `:store` to `Provisioner.evict/2` so teardown clears the
  persistent store when a `Store.File` is in use.

## v0.3.0 (2026-07-03)

### Known limitations
- ~~Claude Managed Agents: sandbox-written files not retrievable~~ **RESOLVED same day
  (post-release probe): it's the outputs-dir convention.** Only files the agent writes
  under `/mnt/session/outputs/` become session artifacts (session-scoped, downloadable);
  files written elsewhere are non-downloadable residue. `Artifacts.ClaudeFiles` works
  as shipped — direct your agent's deliverables to `/mnt/session/outputs/` in its
  system prompt.

### Added
- `ReqManagedAgents.Artifacts` — one vocabulary (`list`/`fetch`/`put`/`delete`,
  name-keyed, session-scoped) over provider-native session storage, with two stores:
  `Artifacts.ClaudeFiles` (Anthropic Files API) and `Artifacts.AgentCoreSessionStorage`
  (AgentCore `sessionStorage` mount, command-backed, report-scale). `%Artifact{}` struct.
- `%SessionInfo{}` handed to handlers via optional `Handler.handle_tool_call/4` and
  `handle_event/3` (existing 3-/2-arity handlers work unchanged);
  `SessionResult.session_id`.
- CMA Files API completion: `Client.list_files/2` (session-scoped via `scope_id`) and
  `Client.delete_file/2`, on `Client.Behaviour` too.
- AgentCore: opaque `environment`/`environment_variables` provision-spec fields
  (filesystem mounts, custom containers, env vars — pass-through, spec-hash covered) and
  `Client.invoke_agent_runtime_command/2` (direct microVM shell; streamed
  stdout/stderr via optional `on_output`; `%AgentCore.CommandResult{}`).

## v0.2.1 (2026-07-03)

### Changed
- Internal code hygiene only — the codebase now passes `mix credo --strict`
  (alias ordering/aliasing, implicit `try`), and CI gates on `--strict` so it
  stays that way. No user-facing changes.

## v0.2.0 (2026-07-03)

### Changed
- Bedrock AgentCore `InvokeHarness` now streams incrementally: turns are guarded by an
  inter-chunk `idle_timeout` (default 300s) instead of a 10-minute whole-body wall clock,
  so long-running turns complete while dead connections fail fast.
- `Handler.handle_event/2` fires live during AgentCore turns (previously only after the
  turn completed) and is documented as at-least-once across retried attempts.
- `Client.new`'s `receive_timeout` now governs control-plane calls only; the invoke data
  plane is guarded by the per-invoke `idle_timeout` instead (callers who used
  `receive_timeout` to cap invokes should now pass `idle_timeout`/`timeout_seconds`).

### Added
- Per-invocation AgentCore server budgets on `Session.run/2` opts: `timeout_seconds`,
  `max_iterations`, `max_tokens` (wire: `timeoutSeconds`/`maxIterations`/`maxTokens`).
- `idle_timeout` opt on the AgentCore invoke path.
- `[:req_managed_agents, :stream, :event]` telemetry now also fires for AgentCore turns.

## v0.1.0 (2026-07-03)

First public release. Provider-agnostic client for **managed agent runtimes**:
the provider runs the agent loop; your custom tools execute locally on your
node. The provider only ever sees each tool's name, description, input schema,
and the text result you return.

### Providers

- `ReqManagedAgents.Providers.ClaudeManagedAgents` — Anthropic Claude Managed
  Agents (public beta, `managed-agents-2026-04-01`). `:streaming` transport
  over long-lived SSE.
- `ReqManagedAgents.Providers.BedrockAgentCore` — AWS Bedrock AgentCore
  Harness (GA) via ConverseStream. `:request_response` transport over
  `application/vnd.amazon.eventstream` (decoded by
  [`aws_event_stream`](https://hex.pm/packages/aws_event_stream)).
  The AWS dependencies (`ex_aws_auth`, `aws_event_stream`) are **optional** —
  Anthropic-only consumers don't pull them; AgentCore raises an actionable
  error at first use if they're missing.

### Core

- `ReqManagedAgents.Provider` behaviour — one canonical turn vocabulary
  across backends: `custom_tool_use` / `custom_tool_result` (client-executed,
  return-of-control tools only), a three-atom terminal
  (`:end_turn | :requires_action | :terminated`), and `%TurnResult{}` /
  `%SessionResult{}` with per-turn token usage.
- Two drivers over the same vocabulary: `ReqManagedAgents.run_to_completion/1` (synchronous) and `ReqManagedAgents.Session` (supervised GenServer;
  reconnect with event consolidation/deduplication, concurrent tool
  execution, full-history paging).
- `ReqManagedAgents.Handler` behaviour for local tool execution;
  `ReqManagedAgents.Provisioner` for idempotent provider-side agent/harness
  provisioning and teardown.
- Anthropic control plane: agents, environments, sessions, events, Files API
  (upload / attach / download).
- Telemetry event tree (`[:req_managed_agents, …]` — request, stream, tool,
  session) with caller metadata injection, plus an optional OpenTelemetry
  bridge emitting `gen_ai.*` spans.

### Hardening (validated against live provider APIs)

- AgentCore ConverseStream tool blocks keyed by `toolUseId` (robust to
  index-reuse in live streams); resume turns carry both the assistant
  `toolUse` and user `toolResult` messages, as the harness requires.
- Exception/error stream frames surface as distinct errors rather than
  silent terminals; bounded per-turn invoke retry on transport errors and
  truncated streams.
- SigV4 signing is session-token aware (works with STS/OIDC temporary
  credentials).
- Client structs redact secrets from `inspect/1` output (`api_key`, AWS
  `credentials`) — a `KeyError` from missing session opts or a crash report
  can't leak them into logs.