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
a00146a

agent-autosuggest v0.2.0

Released 2026-10-25. A minor release. Four changes since v0.1.0: a churn solution
whose feature plans are ready is suggested instead of declined (prompt v5), and the three fixes
from the 2026-10-21 security review. Private repository and image,
docker.io/oramasearch/agent-autosuggest:v0.2.0. Tracking issue:
#25.

This release is the tree of dev at 9b45383 (the merge of #18) with these notes and the version.

What it includes

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

PR Change
#24 Suggest a churn solution whose feature plans are ready, instead of declining it as "transform first" (lake#1153); prompt v5
#20 POST /v1/turn compares the service token in constant time, and refuses every turn when AGENT_SERVICE_TOKEN is unset (#19)
#22 A turn's credential is sent only to Lake at the service's own LAKE_URL (#21)
#18 A turn keeps no trace on the pod's disk (#13)
#17, #16 The v0.1.0 image digest in its notes, and the v0.1.0 release merge brought back into dev

Ready data is suggested, and a real transform names its Lake capability (prompt v5) — #24

Scan my workspace suggested nothing on lake-dev: it declined every churn table and asked for an
"approved snapshot/as_of setup" Lake has no way to make
(lake#1153).

  • solutions.enforce: a runnable solution the model declines as "transform first" is suggested
    instead when every methodology at the chosen level plans ready on one dataset
    (methodologies.ready_dataset). The model's preparation becomes a required_first step, and the
    grounding names the dataset and the cutoff Lake inferred (inferred.as_of).
  • methodologies reads zetta's real transform_required shape and Lake's performed_by. A real
    transform is declined as transform first: <name>: <description>. Lake does it with <capability>.
    Without performed_by the agent falls back to the same mapping.
  • validate: a "transform first" that names no Lake capability (plan_features, upload_dataset,
    workspace_sql, create_dataset_from_query, generate_dataset) is a defect, handed back in the
    repair round.
  • Prompt v5 (PROMPT_VERSION = "v5"): a ready composition is suggested with its preparation in
    required_first; the time role is met by a snapshot column or a declared as_of; "approved
    snapshot" requests are forbidden. v4 is kept in prompts/.

It pairs with lake#1189 (plan_features from a
dataset alone, with its snapshot cutoff, and performed_by). Against a Lake without it, a table with
a date column still plans transform_required; the agent then declines it naming
plan_features/upload_dataset, but suggests nothing for it.

The service token is compared in constant time and always required — #20

turn_refusal() checks the bearer with hmac.compare_digest over bytes. With
AGENT_SERVICE_TOKEN unset or empty, POST /v1/turn answers 503 to every turn (in v0.1.0 the
route was open). A wrong or missing bearer is 401, as before. Turns from Lake's agent bus are
unaffected.

A turn's credential goes only to the service's own LAKE_URL — #22

In v0.1.0 a turn's lake_url and zetta_base_url chose where the turn's bearer was sent.

  • The model gateway and Lake's capabilities (workspace_query, list_apps, ...) are always reached
    at LAKE_URL. A turn's lake_url is ignored.
  • zetta_base_url (Scan my workspace) is accepted only on LAKE_URL's origin and under its path,
    with no user info, query, fragment, backslash or dot segments. Anything else refuses the turn.
  • With LAKE_URL unset, or not an absolute http(s) URL, every turn that would send a credential is
    refused before any request.

No turn trace on the pod's disk — #18

A turn no longer writes <TRACE_DIR>/<trace_id>.json, and the service no longer reads TRACE_DIR;
the Dockerfile drops its default. The answer still carries trace_id, and Lake keeps the whole
answer in the task's sealed record in the turn's workspace Zetta.

Before it rolls: the settings it needs

Setting Needed by Rendered by the operator
AGENT_SERVICE_TOKEN #20: without it every direct turn is refused (503) Yes, on every library agent
LAKE_URL #22: without it (or not absolute http(s)) every turn that sends a credential is refused Yes (Lake's internal URL)
AUTOSUGGEST_MODEL Unchanged; the model name Yes (with AGENT_MODEL, both set to the Lake's agent model)
TRACE_DIR No longer read (#18) Still set to /tmp/traces; ignored

Nothing new is needed from the operator. For the best answers on date-bearing tables, Lake should
carry lake#1189 (merged into lake dev).

Where it has run

  • c5145f4 (#24) ran on lake-dev: pinned as oramasearch/agent-autosuggest:c5145f4 on the
    dev member of the LakeSet lake-nonprod (orama-operator config/clusters/sets/lake-nonprod.yaml,
    orama-operator#982), with lake dev-aa9fefd5. Lake's tools/e2e/agents.py T6 ("Scan my workspace
    keeps its Opportunities") passed there on 2026-10-25.
  • #20, #22 and #18 have not run on dev. They merged after that build. No image of dev's head
    ran on any cluster before this release; they are proven by the test suite below only.
  • Every other Lake runs the operator's default, oramasearch/agent-autosuggest:v0.1.0
    (orama-operator internal/controller/lake_defaults.go).

The image

Built from the tag v0.2.0 (a00146a) on the cluster BuildKit with build-agent.sh (linux/amd64, the repository's Dockerfile, with the catalog context catalog-cf20d264 and the corpus context agent-autosuggest-corpus-a882954), then tagged :v0.2.0 on that digest without rebuilding:

docker.io/oramasearch/agent-autosuggest:a00146a@sha256:5bfd6b393df92a8ba8cd2ea1998050ba353b99dccd145fdbdb261163c810817f, 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.

What it does not include

Unchanged from v0.1.0, except that traces are no longer kept
at all:

  • A trained model. Every turn is a frontier model with few-shot retrieval.
  • A large precedent set. The corpus context at a882954 holds one worked example.
  • Any write. App actions are proposals for a person to confirm; ApplicationAgent performs them.
  • Turn kinds. The task kind is ignored.
  • Workspace identity. Turns carry customer_id; the task's workspace_id is not forwarded (#11).
  • Lease renewal for long turns beyond activity, and back-off on empty bus reads.
  • Bus back-pressure (#23): tasks are claimed before a worker is free.
  • Workspace context from the command line.

Known issues

Security-relevant first. All open at this tag.

  1. The bus claims tasks before a worker is free
    (#23, LSR-075, medium, denial of
    service): lake_bus.work claims every received task into the executor's unbounded queue, so one
    tenant's burst holds task credentials in the process and delays other tenants while their leases
    run. The fix is the port of agent-ask-orama#47.
  2. Library agents hold live task credentials for every tenant they serve
    (lake#871): one shared pod runs every tenant's
    turns with their task credentials.
  3. The workspace is not passed explicitly
    (#11): the agent sends only
    customer_id on its reads, never the task's workspace_id.
  4. The lease is kept by activity only. Lake renews a claim's lease on every capability call made
    with the task credential, so a turn is reclaimed only if one step, such as one model call, outlasts
    lease_seconds (600 by default). Not observed.
  5. The command line validates without workspace evidence
    (#14).
  6. Corpus drafts fail validation
    (agent-autosuggest-corpus#15):
    the corpus's examples do not choose a registry level for S-1. The image keeps the a882954 corpus.

Closed since v0.1.0: #13 (#18),
#19 (#20),
#21 (#22), and
lake#795 (a discover turn failing on list_apps).

Verification

Proof Result
Test suite (uv run --frozen --group dev pytest -q -ra, macOS arm64, Python 3.12.11, on the release branch) 72 tests: 72 passed, 0 failed, 0 skipped. test_service.py 17, test_turn_destinations.py 15, test_service_auth.py 13, test_lake_1153_shapes.py 7, test_solution_evals.py 5, test_lake_bus.py 4, test_apps.py 3, test_solutions.py 3, test_app_evals.py 2, test_release.py 2 (the installed package is 0.2.0; these notes exist and are indexed), test_catalog.py 1
Offline evals (no model) evals/runtime-solutions.jsonl and evals/data-apps.jsonl, run through enforcement and validation inside the suite above; all pass
Live run on lake-dev c5145f4 (#24 only): lake e2e tools/e2e/agents.py T6 passed on 2026-10-25. #20, #22, #18: not run on a cluster
Live-model evals Not run (needs a live model)
Linux image build (cluster BuildKit, from the tag) Built from v0.2.0 with build-agent.sh: oramasearch/agent-autosuggest:a00146a, also :v0.2.0, sha256:5bfd6b393df92a8ba8cd2ea1998050ba353b99dccd145fdbdb261163c810817f; private (404 anonymously)