Skip to content

Release v0.2.0

Choose a tag to compare

@homer6 homer6 released this 25 Oct 21:08
· 35 commits to main since this release
4fd59b5

agent-runtime v0.2.0

Released 2026-10-25. A minor release. Three security fixes from the 2026-10-21 Lake pre-launch
security review (orama-bridge#223) since
v0.1.0. They change behaviour a caller can see, which is why this is a minor release and
not a patch. Private repository and image, docker.io/oramasearch/agent-runtime:v0.2.0. Tracking
issue: #27.

This release is the tree of dev after #26
(fdb6714), with these notes and the version.

What changed

Every pull request merged into dev since v0.1.0
(git log --first-parent v0.1.0..origin/dev):

PR What it does
#16 The v0.1.0 release pull request (dev promoted to main); nothing new
#17 Records the v0.1.0 image digest in the v0.1.0 notes; documentation only
#19 POST /v1/turn compares the service token in constant time, and refuses every turn when AGENT_SERVICE_TOKEN is unset (#18)
#21 A turn's credential is sent only to Lake at this service's LAKE_URL, never to a lake_url the turn names (#20)
#26 A dataset-confined agent's tools are checked against complete dataset identities, and reads that cannot be proven inside the dataset are refused (LSR-181, #23)

The service token is compared in constant time, and required — #19

POST /v1/turn checks the bearer with hmac.compare_digest instead of !=, so the comparison no
longer leaks timing. The route now fails closed: with AGENT_SERVICE_TOKEN unset or empty, every
turn is refused with 503. In v0.1.0 an unset token left the route open. A wrong or missing bearer is
401, as before. Turns from Lake's agent bus are not affected.

A turn's credential goes only to LAKE_URL — #21

A per-turn agent (AgentCreator) made its model client from the turn's lake_url, so a caller of
POST /v1/turn, or a crafted bus task, could have the turn's lake_token sent to a host it named.
The turn's lake_url is no longer read. The model client and the per-turn Lake client both use this
service's LAKE_URL. When LAKE_URL is unset, empty, not an absolute http(s) address, or carries
user info, the turn is refused before any request goes out.

Dataset-confined agents: complete identities, provable reads only — #26

An agent whose work area is a dataset compared only table basenames, and did not check search
targets, so its model calls could reach other datasets the launching person can read. Now:

  • dataset selectors are compared as complete database/table identities, and the authorized
    canonical identity is what is sent to Lake. Slash and dot forms both work; a bare name means Lake's
    default datasets database;
  • only get_dataset and a filtered list_datasets are allowed, their answers are checked against the
    work area, unscoped list metadata is dropped, and server errors are sanitized;
  • every other read and direct action is refused, including both search routes and the App and build
    reads. Pipeline, MCP and definition model tools are left out of dataset-confined runs. Exact
    proposals are still available, since they make no outbound call;
  • an empty or malformed work area, and a missing, malformed or conflicting selector, are refused.

Workspace and project work areas behave as before.

Behaviour changes to know before it rolls

  1. Dataset-confined agents lose some reads (#26). Index search, the App and build reads, and any
    other read that cannot be proven inside the dataset are refused. Index search stays refused until
    Lake can establish an index's source database (Zetta resolves a bare source table across databases
    by first match); the Lake side is lake#1055.
    A grant naming a bare table no longer authorizes the same basename in every database, and legacy
    identities with punctuation outside SQL identifiers fail closed.
  2. A service with no AGENT_SERVICE_TOKEN refuses every turn with 503 (#19). Hand-run services
    that relied on the open route must set the token.
  3. A per-turn service with no valid LAKE_URL refuses every turn (#21), and the turn's lake_url
    field is ignored.

Settings it needs

No new setting. AGENT_SERVICE_TOKEN and LAKE_URL are now required for service mode to take
turns; the operator already renders both (and AGENT_MODEL) on every agent launch, so a launch made
by the operator needs nothing new. git diff v0.1.0..v0.2.0 -- src adds no other environment read.

Not included

Unchanged from v0.1.0. The review's open follow-ups for this
repository are not in this release (below).

Known issues

Security-relevant first.

  1. Customer code can read the service token every library agent accepts: a user-created service
    launch is given Lake's shared agent service token, and definition code runs in the same process
    (#14,
    orama-operator#793 LSR-044,
    lake#1039).
  2. An agent's pods are not network sandboxed
    (lake#725).
  3. The bus consumer claims tasks into an unbounded executor queue before a worker is free, so one
    tenant's burst delays the others and its claims' leases run while queued (LSR-075, medium,
    #24).
  4. Service mode keeps unbounded conversation histories, shared by every tenant on the Lake, keyed
    only by the body's conversation_id (LSR-076, medium,
    #25).
  5. Dataset-confined launch credentials are not yet confined at Lake: the runtime refuses what it
    cannot prove, but the launch token itself still carries the person's reach
    (lake#1055).
  6. The bus client is not yet the workspace-aware cutover client: no workspace_id, no lease
    renewal, no idle backoff (#6).
  7. The solution ledger has no action step through Lake
    (lake#708).

The review's findings for this repository are tracked in
#22.

Where it has run

The v0.2.0 tree has not run on the dev environment. No dev-<sha> build of agent-runtime was
pinned on the dev member of the lake-nonprod set; every member still takes the operator's default
oramasearch/agent-runtime:v0.1.0. Moving the runtime image to :v0.2.0 is a separate operator
change, rolled through testing, staging and prod, each behind its gate.

The image

Built from the tag v0.2.0 (4fd59b5) on the cluster BuildKit with build-agent.sh (linux/amd64, the repository's Dockerfile), then tagged :v0.2.0 on that digest without rebuilding:

docker.io/oramasearch/agent-runtime:4fd59b5@sha256:4c1d49174b924a66ddd3e0d07533957299dcca04fde3fa0d050a56fa6accced6, also tagged :v0.2.0 (same digest). The Docker Hub repository answers 404 anonymously (private).

It is not rolled anywhere yet: pinning it on an environment is a separate change to the operator's set files, through dev, testing, staging and prod in order.

Verification

Proof Result
Test suite (uv run --frozen pytest -q -ra, macOS arm64, Python 3.12) 134 passed, 0 failed, 0 skipped: tests/test_dataset_work_area.py 45 (new, #26), tests/test_runtime.py 25, tests/test_skills.py 31, tests/test_service_auth.py 13 (new, #19), tests/test_turn_destinations.py 9 (new, #21), tests/test_lake_bus.py 4, tests/test_mcp.py 4, tests/test_release.py 3
Skills contract (tests/test_skills.py, in the suite) Every one of the 537 capabilities in the vendored Lake OpenAPI is accounted for; skills.json matches skills.py
Version pyproject.toml and uv.lock 0.2.0; importlib.metadata.version("agent-runtime") and GET /healthz report it (tests/test_release.py)
Live agent runs (a model through Lake's gateway) Not run for this release (needs a live model)
Dev environment Not run (above)
Linux image build (cluster BuildKit, from the tag) Built from v0.2.0 with build-agent.sh: oramasearch/agent-runtime:4fd59b5, also :v0.2.0, sha256:4c1d49174b924a66ddd3e0d07533957299dcca04fde3fa0d050a56fa6accced6; private (404 anonymously)