Files
orchestration_engine/tests/orchestration/test_links.py
Jonathan Boniface 6d32bc696d feat: keep what agents deliver and serve it at signed links (ADR-0004)
The Orchestration engine keeps every completed agent Execution it relays,
by tenant, Customer case and Execution, and serves its record and files at
signed, expiring links. A KAB workflow step, which takes one output per
step, is given one JSON document of links (`deliver: links`); other callers
still get each file, and what they are given is kept either way.

- store.py, links.py, delivery.py, serving.py; the relay keeps and links
- the card declares `deliver`, `sources` and an output schema
- image: STORE_DIR on a /data volume; PUBLIC_URL and LINK_SECRET settings
- option 1's tests replaced by tests of the links document

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-21 20:05:47 +01:00

345 lines
11 KiB
Python

"""Delivered files kept and served at signed links (ADR-0004); a caller that takes
one output per step, as a KAB workflow step does, is given one document of links."""
from __future__ import annotations
import json
import uuid
from typing import Any
from urllib.parse import urlsplit
import httpx
from orchestration.links import Signer
from orchestration.main import create_app
from orchestration.store import Store
from tests.orchestration.test_sequence import (
ARCHITECTURE,
BOTH,
OPERATIONS,
SETTINGS,
ScriptedAgents,
finished,
struct,
)
BASE = "http://orchestration"
# What a KAB workflow step sends with every call.
PLATFORM = {
"workflow_id": "wf-1",
"step_number": 1,
"tenant_id": "t1",
"project_id": "p1",
}
GRAPH = '{"elements": []}'
class Harness:
"""The Orchestration engine in front of scripted agents, with a store and the
caller's client, both in this process."""
def __init__(self, tmp_path: Any, agents: ScriptedAgents) -> None:
self.agents = agents
self.store = Store(tmp_path / "store")
self.app = create_app(
[ARCHITECTURE, OPERATIONS],
SETTINGS,
clients=agents, # type: ignore[arg-type]
sequences=[BOTH],
store=self.store,
signer=Signer("secret", ttl_seconds=3600),
public_url=BASE,
)
def client(self) -> httpx.AsyncClient:
return httpx.AsyncClient(
transport=httpx.ASGITransport(app=self.app), base_url=BASE
)
async def send(self, text: str, metadata: dict[str, Any]) -> dict[str, Any]:
message = {
"messageId": str(uuid.uuid4()),
"role": "ROLE_USER",
"parts": [{"text": text}],
"metadata": metadata,
}
async with self.client() as caller:
response = await caller.post(
"/a2a",
json={
"jsonrpc": "2.0",
"id": 1,
"method": "SendMessage",
"params": {"message": message},
},
headers={"A2A-Version": "1.0"},
)
body = response.json()
assert "error" not in body, body
task: dict[str, Any] = body["result"]["task"]
return task
async def get(self, link: str) -> httpx.Response:
url = urlsplit(link)
async with self.client() as caller:
return await caller.get(
f"{url.path}?{url.query}" if url.query else url.path
)
def document(task: dict[str, Any]) -> dict[str, Any]:
(artifact,) = task["artifacts"]
assert artifact["name"] == "result.json"
loaded: dict[str, Any] = json.loads("".join(p["text"] for p in artifact["parts"]))
return loaded
async def test_a_platform_step_is_given_links_to_what_was_kept(tmp_path):
harness = Harness(
tmp_path,
ScriptedAgents(
{
"architecture": [
finished("a1", {"graph.json": GRAPH, "guide.md": "# Guide"})
]
}
),
)
task = await harness.send(
"A landing zone", {**PLATFORM, "work": "architecture", "customer_case": "acme"}
)
assert task["status"]["state"] == "TASK_STATE_COMPLETED"
result = document(task)
assert result["status"] == "completed"
assert result["work"] == "architecture"
assert result["customer_case"] == "acme"
assert result["execution_id"] == "a1"
assert set(result["files"]) == {"graph.json", "guide.md"}
assert result["record"].startswith(f"{BASE}/tenants/t1/cases/acme/executions/a1?")
# Each link serves what the agent delivered, with its media type.
guide = await harness.get(result["files"]["guide.md"])
assert guide.status_code == 200
assert guide.text == "# Guide"
assert guide.headers["content-type"].startswith("text/markdown")
assert (await harness.get(result["files"]["graph.json"])).json() == {"elements": []}
# The record names the platform's project and links to every file.
record = (await harness.get(result["record"])).json()
assert record["project_id"] == "p1"
assert record["request"] == "A landing zone"
assert set(record["links"]["files"]) == {"graph.json", "guide.md"}
async def test_the_guide_is_the_markdown_the_agent_sent_as_its_document(tmp_path):
harness = Harness(
tmp_path,
ScriptedAgents(
{
"architecture": [
finished(
"a1",
{"graph.json": GRAPH, "notes.md": "n", "guide.md": "# Guide"},
guide="guide.md",
)
]
}
),
)
result = document(
await harness.send("A landing zone", {**PLATFORM, "work": "architecture"})
)
assert result["guide"] == result["files"]["guide.md"]
async def test_a_link_that_is_not_signed_or_was_changed_is_refused(tmp_path):
harness = Harness(
tmp_path,
ScriptedAgents({"architecture": [finished("a1", {"guide.md": "# G"})]}),
)
result = document(
await harness.send(
"A landing zone",
{**PLATFORM, "work": "architecture", "customer_case": "acme"},
)
)
link = result["files"]["guide.md"]
assert (await harness.get(link.split("?")[0])).status_code == 403
assert (await harness.get(link.replace("guide.md", "other.md"))).status_code == 403
assert (await harness.get(link.replace("/t1/", "/t2/"))).status_code == 403
async def test_a_caller_that_asks_for_files_gets_them_and_they_are_kept(tmp_path):
harness = Harness(
tmp_path,
ScriptedAgents({"architecture": [finished("a1", {"graph.json": GRAPH})]}),
)
task = await harness.send(
"A landing zone",
{
**PLATFORM,
"work": "architecture",
"customer_case": "acme",
"deliver": "files",
},
)
assert [a["name"] for a in task["artifacts"]] == ["graph.json"]
assert harness.store.record("t1", "acme", "a1")["files"] == ["graph.json"]
(sent,) = harness.agents.received["architecture"]
assert "deliver" not in struct(sent)
async def test_without_a_tenant_or_case_what_is_kept_is_still_found(tmp_path):
harness = Harness(
tmp_path,
ScriptedAgents({"architecture": [finished("a1", {"graph.json": GRAPH})]}),
)
result = document(
await harness.send(
"A landing zone", {"work": "architecture", "deliver": "links"}
)
)
assert "/tenants/local/cases/unassigned/executions/a1" in result["record"]
assert (await harness.get(result["files"]["graph.json"])).status_code == 200
async def test_a_sequence_is_one_document_with_each_agents_links(tmp_path):
harness = Harness(
tmp_path,
ScriptedAgents(
{
"architecture": [finished("a1", {"graph.json": GRAPH})],
"operations": [finished("o1", {"model.json": "{}"})],
}
),
)
result = document(
await harness.send(
"A landing zone",
{
**PLATFORM,
"work": "architecture_and_operations",
"customer_case": "acme",
},
)
)
assert result["status"] == "completed"
assert result["work"] == "architecture_and_operations"
assert set(result["results"]) == {"architecture", "operations"}
assert set(result["results"]["architecture"]["files"]) == {"graph.json"}
# The top level is the last agent's.
assert result["execution_id"] == "o1"
assert set(result["files"]) == {"model.json"}
assert [r["work"] for r in harness.store.case("t1", "acme")] == [
"operations",
"architecture",
]
async def test_a_sequence_stopped_by_warnings_links_what_was_done(tmp_path):
harness = Harness(
tmp_path,
ScriptedAgents(
{
"architecture": [
finished(
"a1", {"graph.json": GRAPH}, status="completed_with_warnings"
)
],
"operations": [],
}
),
)
result = document(
await harness.send(
"A landing zone", {**PLATFORM, "work": "architecture_and_operations"}
)
)
assert result["status"] == "stopped"
assert result["not_started"] == ["operations"]
assert result["results"]["architecture"]["status"] == "completed_with_warnings"
assert set(result["files"]) == {"graph.json"}
async def test_latest_is_the_newest_completed_execution_of_the_work(tmp_path):
harness = Harness(
tmp_path,
ScriptedAgents(
{
"architecture": [
finished("a1", {"graph.json": "1"}),
finished("a2", {"graph.json": "2"}),
]
}
),
)
first = document(
await harness.send(
"v1", {**PLATFORM, "work": "architecture", "customer_case": "acme"}
)
)
await harness.send(
"v2", {**PLATFORM, "work": "architecture", "customer_case": "acme"}
)
latest = (await harness.get(first["latest"])).json()
assert latest["execution_id"] == "a2"
assert (await harness.get(latest["links"]["files"]["graph.json"])).text == "2"
case = (await harness.get(first["case"])).json()
assert [r["execution_id"] for r in case["executions"]] == ["a2", "a1"]
async def test_sources_given_as_data_reach_the_agent_as_files(tmp_path):
# A platform step maps an earlier step's output into `sources`; whatever was
# parsed on the way is sent on as text, the form an agent reads files in.
harness = Harness(
tmp_path, ScriptedAgents({"operations": [finished("o1", {"model.json": "{}"})]})
)
await harness.send(
"Operate it",
{
"work": "operations",
"sources": {"graph.json": {"elements": []}, "g.md": "# G"},
},
)
(sent,) = harness.agents.received["operations"]
sources = struct(sent)["sources"]
assert json.loads(sources["graph.json"]) == {"elements": []}
assert sources["g.md"] == "# G"
async def test_the_card_declares_the_links_document_and_the_choice_of_delivery(
tmp_path,
):
harness = Harness(tmp_path, ScriptedAgents({}))
async with harness.client() as caller:
skill = (await caller.get("/.well-known/agent-card.json")).json()["skills"][0]
inputs = skill["inputSchema"]["properties"]
assert inputs["deliver"]["enum"] == ["links", "files"]
assert inputs["sources"]["type"] == "object"
outputs = set(skill["outputSchema"]["properties"])
assert {
"status",
"work",
"customer_case",
"record",
"guide",
"files",
"results",
} <= outputs