erlang_adk

# Upgrading Erlang ADK

Version 0.7.0 is cumulative. This guide highlights behavior and deployment
changes introduced by the 0.3-0.7 delivery milestones; it is not a substitute
for the exact contracts in the version documents.

## Before upgrading

1. Read [`FEATURE_PARITY.md`](FEATURE_PARITY.md) and the contracts for every
   milestone being crossed. “Partial” and adapter-owned behavior is not made
   complete by a version bump.
2. Back up deployment-owned Mnesia/session, artifact, memory, evaluation, and
   credential stores. Test restoration and erasure policy in staging.
3. Preserve `rebar.lock` and, for the Phoenix companion, `mix.lock`. Review the
   dependency exceptions in [`SECURITY.md`](../SECURITY.md).
4. Run the complete deterministic and packaging gates before and after the
   upgrade. Run paid provider gates if provider behavior is in scope.
5. Test cancellation, reconnect, continuation, auth expiry, restart, and
   cross-principal isolation with the deployment's adapters and topology.

There is no general automatic schema-migration promise for arbitrary
application session tables or custom adapters. Node-local web sessions, run
lookup, A2A tasks, and Live discovery also do not gain transparent horizontal
failover in 0.7. Stage any persistent-data or multi-node change explicitly.

## Moving to 0.3.0: supervised runtime foundation

- Treat an agent process as an immutable reusable specification and admission
  point. Invocation work runs in separately supervised processes with stable
  IDs, deadlines, budgets, cancellation, events, and one terminal result.
- Enable listeners and persistent services explicitly. The developer API,
  A2A/MCP listeners, Mnesia, and other services are not ambient production
  defaults.
- Consume versioned JSON-safe events rather than internal Erlang records or
  process state.
- Scope continuations and temporary state to an invocation. Do not use browser
  or caller process lifetime as run ownership.
- Configure bounded admission and decide whether overload rejects or enters a
  bounded FIFO queue.

## 0.3.0 to 0.4.0: agents, tools, and workflows

- Distinguish legacy direct turns from fresh invocations. `prompt` and legacy
  `delegate` retain one stateful FIFO compatibility history; Runner and
  explicit invocation/delegated execution use fresh invocation history and
  exact-session lanes.
- Ensure model-visible agent names match `[A-Za-z_][A-Za-z0-9_]*`, avoid the
  reserved `user` name, and construct a true bounded tree: no duplicate
  names, cycles, multiple parents, or unavailable children.
- Compile and validate tool catalogs before provider calls. New dynamic tools
  are invisible until an explicit catalog refresh, and a running agent does
  not automatically swap its catalog.
- Treat model tool arguments as untrusted. Schema, policy, confirmation, and
  credential checks occur before callbacks or side effects.
- Review workflow pause/resume shapes. Top-level sequential/graph/fork paths
  have checkpoint behavior, but nested pauses in parallel branches, loop
  bodies, and transfer members remain limited.

## 0.4.0 to 0.5.0: artifacts, memory, and context

- Supply exact app/user/session or app/user scopes to artifact, memory, and
  context operations. Cross-scope results fail closed rather than being
  silently filtered into a caller's view.
- Move large artifact bytes through deployment-owned bounded adapters. Do not
  put raw multi-megabyte blobs into session history, state, events, or a
  global coordinator mailbox.
- Choose durable adapters and ownership policy explicitly. ETS reference
  implementations are volatile; local Mnesia/filesystem behavior does not
  imply a managed object/vector store, encryption at rest, or distributed
  failover.
- Expect mandatory model-boundary sanitation and complete-request budgeting.
  Tool exchanges remain paired and the current input is not discarded to fit
  a budget.
- Treat context caching as provider prefix/resource reuse, not response
  caching. Cache identities include provider/model/policy/scope information
  and must not expose private provider resource names.
- If enabling exact-scope sharded adapters, size shard admission and storage
  limits for the deployment. Limits are per shard; no global quota is implied.

## 0.5.0 to 0.6.0: authentication, protocols, and Phoenix

- Separate authentication from authorization. A valid token produces an
  issuer-bound identity; a default-deny authorizer must grant each exact
  operation/resource.
- Replace caller-selected provider modules/context with immutable, trusted
  provider profiles and opaque credential references. Use production secret
  storage rather than treating ETS as encrypted durable credential storage.
- For interactive authorization, use the supervised authorization-code flow
  with exact redirects, S256 PKCE, nonce/state, bounded expiry, atomic replay
  claim, and subject binding.
- Update MCP integrations to the supported 2025-11-25 Streamable HTTP
  contract and bind protocol sessions to the authenticated principal.
- Update A2A integrations to the A2A 1.0 JSON-RPC endpoint and send
  `A2A-Version: 1.0`. The legacy `/a2a/prompt` endpoint is not wire-compatible
  and should not be exposed as a production A2A API.
- Keep `/dev` loopback/private and single-operator. Its bearer token is not an
  end-user identity or tool/model credential.
- The Phoenix companion is a same-BEAM BFF. Configure exact OIDC issuer,
  client, callback, scopes, cookie/TLS secrets, and an immutable agent
  catalog; the browser must not select modules, providers, app/user scopes,
  paths, or service PIDs.
- Plan for node locality or sticky routing across the complete login,
  web-session, run, and Live lifetime.

## 0.6.0 to 0.7.0: Live, plugins, evaluation, and observability

### Gemini model separation

Ordinary agents and REST GenerateContent/SSE use:

```erlang
#{provider => adk_llm_gemini,
  model => <<"gemini-3.1-flash-lite">>}
```

Gemini Live is a different WebSocket protocol and uses:

```erlang
#{model => <<"gemini-3.1-flash-live-preview">>}
```

A REST model is rejected by the Live provider. Update automation to use
`ERLANG_ADK_GEMINI_REST=1` for the historical REST suite and
`ERLANG_ADK_GEMINI_LIVE=1` for the Live suite. Historical
`ERLANG_ADK_LIVE_GEMINI` names remain REST-suite compatibility aliases.

### Live sessions and browser voice

- Create and close Live sessions explicitly. Subscribe before waiting for
  readiness, grant bounded credit, and acknowledge each delivered event.
- Subscribers receive future events only. Reconnect may resume provider
  context but does not replay arbitrary media, input, output, or tool side
  effects.
- Use 16 kHz mono PCM s16le for microphone input and expect 24 kHz mono PCM
  s16le model output. Image input is bounded JPEG or PNG.
- Automatic Live tool execution remains off unless trusted application code
  configures an executor, declaration allowlist, scheduling policy, deadline,
  heap bound, and response bound.
- The core supplies an owner-bound voice bridge, not microphone capture or
  playback. The Phoenix reference uses AudioWorklet/Web Audio, exact binary
  acknowledgement, interruption purge, and a same-origin authenticated
  socket.

### Plugins

- Prefer explicit `amend` to continue with a modified value and explicit
  `return` for early completion. The compatibility `{replace, Value}` form is
  an early return, not an amendment.
- Stateful plugin callbacks serialize per instance. Use independent instances
  for plugin-level concurrency; a crashed instance is unavailable rather than
  silently restarted with empty state under a stale PID.
- Revalidate schema, policy, and confirmation after tool-argument amendments.
  Dynamic catalog tools are therefore not amendable in 0.7.

### Evaluation

- Move CI work to versioned eval sets/results and `adk eval run` where useful.
  Exit 0 means pass, exit 2 means a completed evaluation that failed its
  thresholds, and exit 1 means configuration/runtime failure.
- Deterministic criteria remain the reproducible default. The Gemini rubric
  judge is explicit, billable, bounded, and defaults to
  `gemini-3.1-flash-lite`; judge errors count as errors, never passing scores.
- Protect reports as evaluated content. They can contain bounded rationale
  even though provider credentials and raw provider errors are removed.

### Observability

- Adopt v2 operation spans and strict W3C `traceparent`/`tracestate` helpers.
  Automatic propagation through every older MCP, A2A, workflow, task, or
  Phoenix boundary is not claimed.
- Keep content capture off by default. GenAI attributes, metrics, and the
  native OTLP/HTTP JSON exporter exclude prompts, responses, media,
  transcripts, tool arguments/results, credentials, and provider handles.
- The asynchronous bus is bounded best effort, not a durable WAL. Retries can
  duplicate delivery; exhausted work is dropped and counted.

### A2A and Phoenix corrections

- Agent Card `version` now defaults to the loaded `erlang_adk` application
  version instead of a hard-coded 0.6 value. An explicitly configured card
  version still takes precedence. Do not confuse it with the A2A
  `protocolVersion`, which remains `1.0`.
- The explicit Phoenix local identity now works without any `OIDC_*`
  variables, but only in development on exact IPv4 loopback. Login remains a
  CSRF-protected POST and the server owns its principal and scopes.
- Update Phoenix assets and hooks together. The 0.7 browser voice path depends
  on the checked AudioWorklet/resampler, continuous bounded playback, exact
  ACK timing, interruption cleanup, styles, and packaged favicon.

## Post-upgrade validation

Run every gate in [`TESTING.md`](TESTING.md) that applies to the deployment.
Specifically verify:

- no cross-user/session/run/Live visibility;
- exact OIDC callbacks, audiences, algorithms, scopes, and session rotation;
- provider model/config selection and explicit paid-test flags;
- continuation and Live reconnect behavior under process/network loss;
- browser microphone permission cancellation, audio backpressure, and
  interruption cleanup;
- persistent adapter compatibility and restore/erasure behavior; and
- the still-visible Cowlib audit exception before exposing Phoenix.