erlang_adk

# Erlang ADK 0.7.0 release contract

> **Status:** completed and frozen for the v0.7.0 release on 2026-07-15.
> Checked items are release evidence; unchecked items remain explicit
> limitations and were not silently promoted to completed behavior.

Version 0.7 focuses on **multimodal and Gemini Live sessions, Runner-global
plugins, evaluation, and expanded observability**. It builds on the v0.6
authentication and production-boundary work without weakening owner,
principal, deadline, or secret-isolation guarantees.

The target is observable behavior, not a Python object-model port. Live
connections are supervised Erlang processes, independent sessions overlap,
media and subscriber flow is explicitly bounded, and a browser connection is
never allowed to own the lifetime of a model session implicitly.

Primary external contracts:

- [ADK Gemini Live toolkit](https://adk.dev/streaming/) and the
  [Gemini Live WebSocket API](https://ai.google.dev/api/live): bidirectional
  text/audio/video, tool calls, interruption, transcription, usage, GoAway,
  context compression, and session resumption;
- [ADK plugins](https://adk.dev/plugins/): ordered Runner-global lifecycle
  hooks that observe, amend, or short-circuit agent/model/tool execution before
  corresponding object-local callbacks;
- [ADK evaluation](https://adk.dev/evaluate/): versioned multi-turn datasets,
  response and trajectory/tool-use criteria, repeatable reports, and CI use;
- [ADK observability](https://adk.dev/observability/) and
  [OpenTelemetry GenAI semantic conventions](https://opentelemetry.io/docs/specs/semconv/registry/attributes/gen-ai/):
  correlated traces, metrics, structured events, and opt-in content capture.

## Starting point

The v0.6 release provides canonical bounded text/inline/file/function content,
REST one-shot and SSE content streaming, ordered isolated Runner plugins,
versioned concurrent evaluation sets, correlated `telemetry` envelopes, and
bounded exporters. It deliberately does not call REST SSE “Live”.

Known v0.7 gaps at branch start:

1. No Gemini Live WebSocket protocol, supervised session, interruption,
   resumption, GoAway, realtime media, transcription, or Live tool-call API.
2. Plugin callbacks are isolated but do not expose an explicit amend versus
   early-return distinction, a supervised stateful instance contract, or
   reusable core plugins.
3. Evaluation lacks built-in trajectory match policies, repeated sampling,
   baseline regression comparison, portable reports, and a v2 CLI path.
4. Observability has correlation envelopes but no W3C propagation,
   OpenTelemetry GenAI mapping, asynchronous bounded export bus, Live-session
   telemetry, or bounded metric aggregation.

## Architectural decisions

1. **Live is a separate protocol.** `gemini-3.1-flash-lite` remains the normal
   REST default; Live examples use `gemini-3.1-flash-live-preview` explicitly.
2. **One Live session is one supervised process.** The process owns exactly one
   active WebSocket, protocol state, bounded input admission, resumption token,
   and subscriber registry. Reconnect replaces the connection, not the stable
   session identity.
3. **Media flow is credit based.** Subscriber credit and byte/event limits
   prevent slow UI or audio consumers from turning BEAM mailboxes into media
   buffers. Input chunks, queues, decoded frames, tool calls, and transcripts
   have explicit limits.
4. **Credentials remain server-side.** API keys and resumption/ephemeral tokens
   never enter public events, logs, plugin contexts, evaluation data, or
   browser state. Direct browser-to-Gemini ephemeral-token provisioning is an
   application adapter, not a default core path.
5. **Plugin ordering stays deterministic.** Plugins run in registration order
   before corresponding local callbacks. Amend continues with a new value;
   early return skips remaining plugins, the local callback, and the guarded
   operation. Each callback remains deadline/heap/owner bounded.
6. **Evaluation separates facts from judges.** Deterministic response and
   trajectory criteria remain reproducible. LLM/managed judges use explicit
   adapters, model/version metadata, sample counts, deadlines, and error
   accounting; judge errors never become passing scores.
7. **Observability is metadata-first.** GenAI semantic attributes, W3C trace
   context, metrics, and events exclude content by default. Content capture is
   opt-in, bounded, recursively secret-pruned, and marked in every envelope.
8. **Export cannot create unbounded backpressure.** Synchronous fail-closed
   exporters remain available for policy gates; production telemetry can use
   a supervised bounded asynchronous bus with explicit drop accounting.

## Delivery phases

### A. Gemini Live protocol and multimodal sessions

- [x] Add a strict versioned Live client/server-message codec with text,
  PCM audio, image/video frames, activity signals, tool responses,
  transcriptions, usage, interruption, cancellation, GoAway, and resumption.
- [x] Track the current Gemini Live response schema, including interim input
  transcription, optional transcription metadata, completion reason/wait
  metadata, and server voice/VAD signals, with strict bounds and no dynamic
  provider atoms.
- [x] Add a production Gun WebSocket transport with peer verification,
  connection/setup deadlines, secret-safe failures, and response bounds.
- [x] Add independently supervised Live sessions with stable opaque refs,
  owner-aware control, bounded input admission, status, close, reconnect, and
  a race-safe supervisor-wide admission ceiling.
- [x] Add capped credit/ack subscriber admission, capacity recovery on detach
  or process death, slow-subscriber detachment, and exact byte/event
  accounting for bounded per-subscriber in-flight and queued events.
- [x] Add opt-in trusted Live tool execution with correlated IDs, explicit
  sequential versus bounded-concurrent local scheduling, cancellation, and
  bounded tool responses while preserving synchronous provider semantics.
- [x] Add deterministic fake-transport coverage and an opt-in real
  `gemini-3.1-flash-live-preview` gate.
- [ ] Add a separate local CA-controlled TLS WebSocket lifecycle harness.

Live limitations: subscribers receive events produced after subscription;
there is no historical structural-event replay yet. Deterministic fake
transport coverage is complete and the paid real-Live gate passes all five
text/transcription, PCM, image, synchronous-tool, and browser-bridge cases;
the separate local CA-controlled TLS WebSocket lifecycle harness remains open.
Automatic tool execution requires an explicit
trusted executor module, declared-tool allowlist, scheduling policy, worker
deadline, heap bound, and response bound; it is never inferred from an ambient
tool catalogue. A reconnect cancels in-flight/queued tool work and never
replays media, input, tool responses, or side effects. Caller-supplied
`session_id` values are correlation labels rather than unique registry keys;
the stable runtime identity is the supervised session reference/PID, and
developer lookup fails closed when labels are ambiguous. Opt-in Live v2 spans
and bounded metrics are metadata-only: media/text/transcripts, tool
arguments/results, credentials, and resumption handles cannot be captured by
the Live observability configuration.
Per-session subscriber admission defaults to 64 (hard maximum 4096). The
application-wide `live_session_limit` defaults to 1024 (hard maximum 16384);
capacity failures are explicit and admission does not enumerate children.

### B. Plugin lifecycle and reusable capabilities

- [x] Add explicit `amend` and `return` outcomes while preserving the v0.6
  compatibility result forms.
- [x] Stop remaining plugins and local callbacks after an explicit early
  return; preserve registration order for observation/amendment.
- [x] Harden callback workers with absolute deadlines, aliases, completion
  timestamps, caller monitoring, off-heap mailboxes, and shared-binary-aware
  heap limits.
- [x] Add an optional supervised stateful plugin-instance contract with hard
  ID/config/queue/deadline/heap/state bounds, owner-liveness commit semantics,
  bounded status, and deterministic shutdown.
- [x] Add reusable global-instruction, context-filter, logging, and tool-retry
  plugins where the existing Runner boundary can enforce their behavior.

Plugin limitations: tool-argument amendments are accepted only where the
runtime can repeat schema, policy, and confirmation checks; dynamically
resolved catalogue tools are therefore not amendable. Stateful callbacks are
serialized per plugin instance, so independent instances are the supported
way to obtain plugin-level concurrency. Reflect/retry emits bounded retry
guidance but does not automatically replay potentially non-idempotent tools.
A stateful instance PID is deliberately a temporary supervisor child: a crash
makes it unavailable rather than silently restarting with empty state behind a
stale identity. Initialization is isolated, but persistent/restarted plugin
state remains an application adapter.

### C. Evaluation expansion

- [x] Add deterministic built-in exact-response and tool-trajectory criteria
  with exact/in-order/any-order/subset matching and exact/subset/ignored
  argument policies.
- [x] Add a first-party bounded rubric/LLM judge adapter with explicit
  judge-schema, requested-model, rubric-ID, and rubric-version metadata. It
  defaults to `adk_llm_gemini`/`gemini-3.1-flash-lite` and is never selected
  or invoked implicitly.
- [x] Add repeated samples, deterministic sample IDs, aggregate distributions,
  pass thresholds, and explicit partial/judge-error accounting.
- [x] Add baseline comparison with configurable regression tolerances and
  stable JSON/Markdown reports suitable for CI artifacts.
- [x] Add a versioned `adk eval run` CLI path while preserving the legacy
  `adk evaluate` command and its output contract. Completed-but-failing gates
  use exit code 2; configuration/runtime failures use exit code 1.
- [x] Add bounded dataset/report size, case/sample concurrency, owner cleanup,
  and deadline-late-result tests.

Evaluation limitations: built-in criteria are deterministic and local. The
versioned CLI criteria file intentionally accepts only those checked built-ins;
trusted applications can register custom `score/4` or full-case
`score_case/2` modules through the Erlang API. The first-party rubric judge is
also an explicit Erlang-API module, not a hidden CLI or browser-selected call.
It stores a bounded rationale as evaluation content, while excluding provider
credentials and raw provider errors. Managed Vertex evaluation remains an
explicit future adapter, and every judge transport/schema/timeout error is
accounted as an error rather than a passing score.

The production CLI adapter creates one fresh supervised agent and Runner
session per case/sample. A lightweight guardian monitors the bounded sample
worker and owns the active stream, agent, and session, including timeout,
max-heap, and caller-death cleanup. Custom adapters which allocate external
resources must provide the equivalent owner monitor: `terminate_case/3` is
best-effort teardown and cannot run after an untrappable worker kill.

JSON eval-set and saved-result inputs and rendered reports are capped at 16 MiB
in the CLI; criteria and agent configuration files retain the stricter 1 MiB
configuration boundary. Report files are replaced atomically. Stdout and file
delivery contain the same newline-terminated bytes. With a baseline, the CI
gate requires both the current absolute thresholds and the configured
regression tolerances to pass.

### D. Expanded observability

- [x] Add strict W3C `traceparent`/`tracestate` parse, format, child-span, and
  explicit HTTP extraction/injection helpers; Runner model/tool and Live spans
  carry the checked context. Automatic propagation through every pre-existing
  MCP, A2A, workflow, task, and Phoenix call is not claimed.
- [x] Map lifecycle envelopes to stable OpenTelemetry GenAI operation,
  provider, model, tool, usage, output-type, error, and duration attributes.
- [x] Add a supervised asynchronous export bus with bounded queue/batches,
  exporter concurrency, retry policy, drain, and dropped-event counters.
- [x] Add a bounded low-cardinality metric registry plus operation
  count/duration/error and Live lifecycle/media/tool instruments; plugin and
  evaluation-specific product metrics remain application-defined records.
- [x] Add an opt-in, SDK-independent OTLP/HTTP JSON exporter while preserving
  the no-exporter path for applications that use only core `telemetry` events.

Observability limitations: the v0.7 native exporter implements OTLP/HTTP JSON,
not OTLP Protobuf, OTLP/gRPC, or an OpenTelemetry SDK bridge. It sends one
completed v2 span (or one metadata-only v1 log envelope) per request; v2 start
signals are local notifications and are not exported. It does not yet batch,
gzip, or pool collector connections inside the exporter--batch admission,
bounded parallel workers, transient retry, and drain remain responsibilities
of `adk_observability_bus`. Explicitly captured content is rejected at the
OTLP boundary, and prompt/response/media/tool-payload and credential-shaped
attributes are never mapped. Collector endpoints are configured as a strict
HTTP(S) origin plus bounded trace/log paths; plain HTTP is intended only for a
trusted local or private collector. Redirects are never followed, HTTPS uses
peer and hostname verification, request/response/header sizes are bounded,
and endpoint, header, and response-body values never enter failure terms.
OTLP retryable status codes (429, 502, 503, 504) and transport failures are
marked transient; other status codes and partial success rejections are
marked permanent, so the bus does not replay them. A numeric `Retry-After` is
present in the exporter's direct structural error, but the shared v0.7 bus
does not yet retain that hint or provide OTLP-specific jitter; it uses capped
exponential delayed retries within the same event/byte capacity as its ready
queue. Delivery is bounded best effort rather than a durable WAL: retries may
duplicate a batch and exhausted work is dropped and counted. The GenAI
semantic mapping remains explicitly pinned while the upstream convention is
Development.

### E. Integrated developer and Phoenix tooling

- [x] Add bounded Live status/text/future-only SSE and content-free
  observability snapshots without exposing media, credentials, resumption
  handles, thought signatures, or unrestricted content. A trace archive is not
  claimed.
- [x] Add a Phoenix LiveView reference path for server-owned Live sessions,
  future-only credit/ack event delivery, realtime text, and teardown, using a
  server-only opaque attachment handle after bounded discovery.
- [x] Add an authenticated same-origin binary voice socket backed by one
  owner-bound lightweight Erlang bridge, automatic-VAD/active-state admission,
  exclusive per-session leases, reconnect continuity capabilities, timed
  authorization revalidation, bounded AudioWorklet capture/resampling and
  cross-thread credit, native playback, exact ACK credit, interruption, and
  fail-closed ambiguous-outcome/reconnect teardown.
- [x] Add evaluation report/comparison and observability views with exact
  authorization and bounded rendering; keep `/dev` loopback-only.

### F. Documentation and release evidence

- [x] Update README examples and the F-ledger as each public API lands.
- [x] Reconcile `FEATURE_PARITY.md` and this contract with proven behavior and
  explicit limitations.
- [x] Complete clean compile/EUnit/Common Test/Dialyzer, README, CLI,
  concurrency, Phoenix, and packaging gates.
- [x] Raise the verified production runtime to OTP 27.3.4.14 / SSL 11.2.12.10
  and rerun deterministic, Phoenix, package, direct-TLS, REST, and Live gates
  on that security patch level.
- [x] Enforce loopback-only startup for the unauthenticated legacy
  `/a2a/prompt` route, including IPv4/IPv6 wildcard rejection independent of
  A2A v1 public-listener flags.
- [x] Run opt-in REST Gemini and Live Gemini suites with no skipped cases;
  provider/quota failures are reported and never counted as passes. Live is
  5/5; REST is 15/17 with two explicit HTTP 429 failures, while the new
  first-party rubric-judge case passes.
- [x] Run the Phoenix dependency audit and keep the two unresolved upstream
  Cowlib advisories explicit rather than treating the non-zero audit as pass.

## Explicit non-goals unless completed later on this branch

- The core does not capture microphones/cameras, resample PCM, render video, or
  play audio. It now supplies an owner-bound, bounded binary voice bridge; the
  checked Phoenix companion demonstrates the application-owned AudioWorklet
  capture/resampling and Web Audio playback pipeline.
- A Live WebSocket is not a durable queue. Resumption uses provider handles and
  bounded local state; it does not promise replay of arbitrary lost media.
- Browser-direct Gemini connections require a deployment-owned ephemeral-token
  endpoint, origin policy, rate limits, and abuse controls.
- Managed Vertex evaluation services and hosted observability backends remain
  adapters; deterministic local criteria and vendor-neutral telemetry are core.
- Reasoning traces, prompts, tool arguments/results, media, and transcripts are
  not captured merely because observability is enabled.