Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 5 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,10 @@ Current release: [v0.2.7](docs/releases/v0.2.7.md) ([all releases](docs/releases
The Python service exposes `POST /v1/turn` and `GET /healthz` (which reports the `version`) on port
8080. `POST /v1/turn` requires `Authorization: Bearer <AGENT_SERVICE_TOKEN>`, compared in constant time (`401` otherwise), and fails closed: with `AGENT_SERVICE_TOKEN` unset or empty it refuses every turn with `503`. The operator always sets it; set it yourself for a hand-run service. Turns from lake's bus do not use it. It can also receive `agent_turn` tasks (lake gives them kind `app`) from lake's agent bus when
`LAKE_URL` and `AGENT_BUS_TOKEN` are set; `AGENT_BUS_AGENT` names the agent and defaults to
`agent-application`. Every app deployment remains subject to an explicit confirmation carried on a
`agent-application`. Bus tasks are claimed by reference (lake#871): no task credential reaches the
process, and every call made for a task carries the bus credential and `X-Lake-Agent-Task: <task
id>`, falling back to the body's credential on a Lake that refuses it
([service and bus operation](docs/operations/service.md)). Every app deployment remains subject to an explicit confirmation carried on a
follow-up turn. A confirmed proposal that needs packages outside app-runtime's baked set is first
stored as a source-backed runtime App, built by lake, and deployed from the resulting immutable
image reference.
Expand Down Expand Up @@ -72,7 +75,7 @@ which lake grants only when the person opted in and attempts remain, applies its

## Verification and evals

`uv run pytest` covers the service, bus, proposal rules, confirmation gate, deployment calls, and
`uv run pytest` covers the service, bus (with claims by reference, `tests/test_by_reference.py`), proposal rules, confirmation gate, deployment calls, and
generated Apps loaded by the pinned app-runtime revision, and whether a generated Streamlit App's sidebar
filters reach every metric, chart and table (agent-application#64): the App runs under Streamlit's
`AppTest` over a SQLite copy of its dataset and each filter is chosen in turn
Expand Down
14 changes: 12 additions & 2 deletions docs/operations/service.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,18 @@ credential only for the duration of the turn.
The lake agent bus is enabled when `LAKE_URL` and `AGENT_BUS_TOKEN` are set; `AGENT_BUS_AGENT`
names the agent and defaults to `agent-application`.
The worker long-polls `receive_agent_tasks`, claims each task once, and publishes progress followed
by a result or failure. The bus credential is used only for those three bus capabilities. The
person's delegated credential remains inside the claimed task body.
by a result or failure. Those three bus calls carry the bus credential alone.

**No task credential reaches this process** (lake#871, lake `docs/api/agent-bus.md`). Each claim
asks for `credentials: by_reference`: Lake keeps the task's credential and answers the body without
it (`lake_bus.task_credentials`). Every call the turn makes to Lake (its capability reads and writes,
and its model calls through the gateway) then carries this agent's bus credential and the header
`X-Lake-Agent-Task: <task id>`, which Lake honours only while that task is claimed and `Running` on
this agent. The bus calls themselves never send the header. The proposal and change checks that
refuse an answer containing the turn's `lake_token` now refuse one containing the bus credential. A
Lake from before lake#871 refuses the `credentials` field before claiming anything; the claim is then
asked again without it, and the body's own `lake_token` is used as before, with no task header. Lake
removes the in-body mode once every library agent claims by reference.

The model is `APPLICATION_AGENT_MODEL` when it is set, else `AGENT_MODEL`, else `gpt-6.1-sol`. The Orama
operator sets `AGENT_MODEL` on every library agent pod from the Lake's `spec.agents.model`, so the
Expand Down
8 changes: 7 additions & 1 deletion src/agent_application/agent.py
Original file line number Diff line number Diff line change
Expand Up @@ -114,6 +114,9 @@ class Turn:
# `app` builds a new App; `repair` and `change` work on the existing App in
# `context.app_id` (lake#1207, repair.py).
kind: str = "app"
# Sent with `lake_token` on every call to Lake for the turn: `X-Lake-Agent-Task` when the turn
# was claimed by reference (lake#871), empty otherwise.
lake_headers: dict[str, str] = field(default_factory=dict)


class LakeError(Exception):
Expand Down Expand Up @@ -143,7 +146,10 @@ def __init__(
self.client = httpx.Client(
base_url=turn.lake_url.rstrip("/"),
timeout=180.0,
headers={"Authorization": f"Bearer {turn.lake_token}"},
headers={
**turn.lake_headers,
"Authorization": f"Bearer {turn.lake_token}",
},
transport=transport,
)

Expand Down
75 changes: 68 additions & 7 deletions src/agent_application/lake_bus.py
Original file line number Diff line number Diff line change
@@ -1,4 +1,12 @@
"""Receive ApplicationAgent turns from lake's agent bus."""
"""Receive ApplicationAgent turns from lake's agent bus.

Each claim asks for `credentials: by_reference` (lake#871, lake docs/api/agent-bus.md): Lake
answers the turn's body with no credential in it, and the turn calls Lake with this agent's bus
credential and the header `X-Lake-Agent-Task: <task id>`, which Lake honours only while the task
is claimed and Running on this agent (`task_credentials`). A Lake from before lake#871 refuses the
field; the claim is then asked again without it and the body carries the task's own credential, as
before.
"""

from __future__ import annotations

Expand Down Expand Up @@ -34,6 +42,51 @@ class BusError(Exception):
def __init__(self, code: str, message: str) -> None:
super().__init__(f"{code}: {message}")
self.code = code
self.message = message


# Task credentials by reference (lake#871, lake docs/api/agent-bus.md, "Task credentials by
# reference"): a claim asks Lake to keep the task's credential, so this process, which serves every
# tenant, never holds one. Each call made for the task carries this agent's bus credential and
# TASK_HEADER, naming the task; Lake acts as the task only while it is claimed and Running here.
TASK_HEADER = "X-Lake-Agent-Task"
BY_REFERENCE = "by_reference"
# The body fields Lake fills with the task's credential ("{{credential}}" at dispatch).
CREDENTIAL_FIELDS = ("lake_token", "zetta_token")


def refuses_by_reference(error: BusError) -> bool:
"""A Lake from before lake#871 refuses the claim's `credentials` field as unexpected, before
it claims anything, so the claim can be asked again without it."""
return error.code == "invalid_input" and "credentials" in error.message


def task_credentials(token: str, claimed: dict[str, Any]) -> dict[str, Any]:
"""The claimed task's body, with the credential its calls to Lake use.

Claimed by reference, Lake answered every credential field empty: they are filled with this
agent's bus credential (`token`), and `lake_headers` holds `X-Lake-Agent-Task: <task id>`,
which every call made for the task sends with it. Claimed with the credential in the body (a
Lake from before lake#871), the body is used as it came, as before.
"""
body = dict(claimed.get("body") or {})
if claimed.get("credentials") != BY_REFERENCE:
return body
for name in CREDENTIAL_FIELDS:
if name in body:
body[name] = token
body["lake_headers"] = {TASK_HEADER: str(claimed["task_id"])}
return body


def task_headers(body: dict[str, Any]) -> dict[str, str]:
"""The headers a turn sends with its credential on every call to Lake: `X-Lake-Agent-Task`
for a task claimed by reference (`task_credentials`), none for any other turn."""
headers = body.get("lake_headers")
if not isinstance(headers, dict):
return {}
value = headers.get(TASK_HEADER)
return {TASK_HEADER: value} if isinstance(value, str) and value else {}


class LakeBus:
Expand Down Expand Up @@ -96,12 +149,20 @@ def receive(self, from_sequence: int) -> tuple[list[dict[str, Any]], int]:
return list(tasks), next_sequence

def claim(self, task_id: str) -> dict[str, Any] | None:
"""The claimed task, or None when another replica took it first. Asked by reference
(lake#871); a Lake that refuses that is asked again for the credential in the body."""
arguments = {"task_id": task_id, "agent": self.agent}
try:
return self.call(
"claim_agent_task",
{"task_id": task_id, "agent": self.agent},
read=False,
)
try:
return self.call(
"claim_agent_task",
{**arguments, "credentials": BY_REFERENCE},
read=False,
)
except BusError as error:
if not refuses_by_reference(error):
raise
return self.call("claim_agent_task", arguments, read=False)
except BusError as error:
if error.code in {"conflict", "not_found"}:
return None
Expand Down Expand Up @@ -140,7 +201,7 @@ def run_task(
except BusError as error:
_log(task=task_id, progress_not_published=str(error))
try:
answer = handle(claimed.get("body") or {})
answer = handle(task_credentials(bus.token, claimed))
except Exception as error:
answer = {"ok": False, "error": f"{type(error).__name__}: {error}"}
if answer.get("ok"):
Expand Down
10 changes: 7 additions & 3 deletions src/agent_application/model.py
Original file line number Diff line number Diff line change
Expand Up @@ -18,8 +18,12 @@ def gateway_url(lake_url: str) -> str:


def gateway_client(lake_url: str, lake_token: str,
http_client: httpx.Client | None = None) -> OpenAI:
"""An OpenAI client whose every call goes through lake for this run."""
http_client: httpx.Client | None = None,
headers: dict[str, str] | None = None) -> OpenAI:
"""An OpenAI client whose every call goes through lake for this run. `headers` go with every
call: a turn claimed by reference sends `X-Lake-Agent-Task` with the bus credential as its key
(lake#871, `lake_bus.task_credentials`)."""
if not lake_url or not lake_token:
raise ValueError("a model call needs lake's URL and the run's lake credential")
return OpenAI(base_url=gateway_url(lake_url), api_key=lake_token, http_client=http_client)
return OpenAI(base_url=gateway_url(lake_url), api_key=lake_token, http_client=http_client,
default_headers=dict(headers or {}) or None)
4 changes: 3 additions & 1 deletion src/agent_application/service.py
Original file line number Diff line number Diff line change
Expand Up @@ -115,6 +115,7 @@ def run_turn(
history = state.history(conversation_id)
if not history:
history.extend(seeded_history(body.get("history")))
headers = lake_bus.task_headers(body)
turn = Turn(
message=message,
lake_url=lake_url,
Expand All @@ -123,13 +124,14 @@ def run_turn(
conversation_id=conversation_id,
context=body.get("context") if isinstance(body.get("context"), dict) else {},
kind=str(body.get("kind") or "app"),
lake_headers=headers,
)
# The model is reached through lake with the turn's own key, which counts its tokens in the
# turn's workspace (lake#248); this agent holds no provider key.
answer = answer_turn(
turn,
history,
client or gateway_client(lake_url, token),
client or gateway_client(lake_url, token, headers=headers),
state.model,
lake,
)
Expand Down
Loading