feat: build on kept work by reference with sources_from (ADR-0004 phase 2)

A request names work the Orchestration engine kept instead of carrying its
files: a record or latest link from an earlier document of links (checked,
and of the request's tenant and Customer case), latest/<work>, or an
Execution's id. The kept files and the record that the work completed are
the agent's sources. Nothing starts, and the caller is told why, when the
reference does not resolve to completed work it may use.

A sequence's next agent is given what was kept of the one before, the same
way.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-21 21:00:26 +01:00
parent 6d32bc696d
commit 1ec939f4fd
8 changed files with 430 additions and 19 deletions

View File

@@ -158,6 +158,14 @@ def input_contract(
"`files`: another agent's delivered work."
),
},
"sources_from": {
"type": "string",
"description": (
"Work kept earlier to start from instead of its files: an "
"earlier step's `record` or `latest` link, `latest/<work>`, "
"or an Execution's id in this Customer case."
),
},
"deliver": {
"type": "string",
"enum": ["links", "files"],

View File

@@ -3,11 +3,12 @@ signer and the address a caller reaches them at, together."""
from __future__ import annotations
import json
import logging
import re
from collections.abc import Mapping
from typing import Any
from urllib.parse import quote
from urllib.parse import parse_qs, quote, unquote, urlsplit
from orchestration.links import Signer
from orchestration.store import Store
@@ -16,7 +17,11 @@ logger = logging.getLogger(__name__)
LOCAL_TENANT = "local" # what is kept for a caller that names no tenant
UNASSIGNED = "unassigned" # for a request that names no Customer case
# The Orchestration engine's own record that an Execution completed, sent with its
# files to the agent that builds on them.
RECORD = "execution.json"
_NOT_SLUG = re.compile(r"[^A-Za-z0-9._-]+")
_KEPT_PATH = re.compile(r"^/tenants/([^/]+)/cases/([^/]+)/(executions|latest)/([^/]+)$")
def _slug(value: Any, default: str) -> str:
@@ -68,6 +73,76 @@ class Delivery:
logger.exception("Could not keep %s Execution %s", work, execution_id)
return None
# --- building on what was kept (phase 2) ---------------------------------------
def resolve(self, reference: str, fields: Mapping[str, Any]) -> dict[str, Any]:
"""The kept Execution a request names in `sources_from`: a link from an
earlier document, `latest/<work>`, or an Execution's id in the request's
Customer case. Raises ValueError, saying why, for anything else."""
tenant, case = self.place(fields)
named_case = fields.get("customer_case")
if reference.startswith(("http://", "https://", "/")):
url = urlsplit(reference)
query = parse_qs(url.query)
exp, sig = (query.get(key, [None])[0] for key in ("exp", "sig"))
if not self.signer.verify(url.path, exp, sig):
raise ValueError("The link in sources_from is not valid.")
match = _KEPT_PATH.match(url.path)
if not match:
raise ValueError("The link in sources_from is not to kept work.")
tenant_of, case, kind, ident = match.groups()
if fields.get("tenant_id") and tenant_of != tenant:
raise ValueError("The link in sources_from is of another tenant.")
tenant = tenant_of
if named_case and _slug(named_case, UNASSIGNED) != case:
raise ValueError(
f"The work in sources_from is of the Customer case {case}, "
f"not {named_case}."
)
ident = unquote(ident)
record = (
self.store.record(tenant, case, ident)
if kind == "executions"
else self.store.latest(tenant, case, ident)
)
elif reference.startswith("latest/"):
work = reference.removeprefix("latest/")
record = self.store.latest(tenant, case, work)
if record is None:
raise ValueError(
f"No {work} work has completed in the Customer case {case}."
)
else:
record = self.store.record(tenant, case, reference)
if record is None:
raise ValueError(
f"Nothing is kept for {reference!r} in the Customer case {case}."
)
if record["status"] != "completed":
raise ValueError(
f"The {record['work']} work {record['execution_id']} ended "
f"{record['status']}; only work that completed is built on."
)
return record
def sources(self, record: Mapping[str, Any]) -> dict[str, str]:
"""A kept Execution as an agent's sources: its files, with the record that
it completed."""
files = self.store.files(
record["tenant"], record["customer_case"], record["execution_id"]
)
completion = {
"status": record["status"],
"customer_case": record["customer_case"]
if record["customer_case"] != UNASSIGNED
else None,
"execution_id": record["execution_id"],
"workflow_request": record["request"],
"work": record["work"],
}
files[RECORD] = json.dumps({k: v for k, v in completion.items() if v})
return files
# --- addresses -------------------------------------------------------------
@staticmethod

View File

@@ -44,7 +44,7 @@ from google.protobuf import json_format
from orchestration.agents import Agent
from orchestration.agents import Sequence as AgentSequence
from orchestration.delivery import Delivery
from orchestration.delivery import RECORD, UNASSIGNED, Delivery
from orchestration.routing import WORK, route
logger = logging.getLogger(__name__)
@@ -62,9 +62,8 @@ _PAUSES = {TaskState.TASK_STATE_INPUT_REQUIRED, TaskState.TASK_STATE_AUTH_REQUIR
# What every agent of a sequence is sent of the caller's fields. The rest go to the
# first agent only, or to the agent whose work names them: `operating_model: {...}`.
_CARRIED = ("customer_case", "pre_approved", "request")
# The Orchestration engine's own record that an agent's Execution completed, sent
# with its files to the next agent.
RECORD = "execution.json"
# Where a request names work kept earlier to build on (ADR-0004, phase 2).
SOURCES_FROM = "sources_from"
# How a caller is given what agents delivered (ADR-0004): one document of links to
# what was kept, or each file as the agent sent it.
DELIVER, LINKS, FILES = "deliver", "links", "files"
@@ -87,6 +86,8 @@ class Plan:
deliver: str = FILES
# Each agent that completed, by its work: its Execution, how it ended, links.
results: dict[str, dict[str, Any]] = field(default_factory=dict)
# What was kept of each, by its work, for the agent after it to build on.
kept: dict[str, dict[str, Any]] = field(default_factory=dict)
def metadata(self, step: int, sources: Mapping[str, str] | None) -> dict[str, Any]:
"""The metadata for the agent at `step`."""
@@ -203,8 +204,36 @@ class RelayExecutor(AgentExecutor):
work=str(options.get(WORK) or decision.agents[0].work),
deliver=_deliver(options),
)
if SOURCES_FROM in fields:
try:
self._build_on(fields)
except ValueError as exc:
await updater.complete(
updater.new_agent_message(
[
new_text_part(f"Nothing was started: {exc}"),
new_data_part(
{"status": "not_started", "reason": str(exc)}
),
]
)
)
return
await self._run(task_id, plan, 0, self._opening(plan, 0, None), updater)
def _build_on(self, fields: dict[str, Any]) -> None:
"""Make the work a request names in `sources_from` its sources, and its
Customer case the request's when it names none."""
reference = str(fields.pop(SOURCES_FROM) or "")
if self._delivery is None:
raise ValueError("Nothing is kept here to build on.")
if fields.get("sources"):
raise ValueError("Give sources or sources_from, not both.")
record = self._delivery.resolve(reference, fields)
if not fields.get("customer_case") and record["customer_case"] != UNASSIGNED:
fields["customer_case"] = record["customer_case"]
fields["sources"] = self._delivery.sources(record)
async def _resume(
self,
task_id: str,
@@ -381,6 +410,7 @@ class RelayExecutor(AgentExecutor):
else None
)
if record is not None and self._delivery is not None:
plan.kept[agent.work] = record
result.update(self._delivery.links(record))
else:
result["files"] = {name: None for name in sorted(files)}
@@ -429,17 +459,22 @@ class RelayExecutor(AgentExecutor):
not_started,
)
return
record = {
"status": "completed",
"customer_case": plan.fields.get("customer_case"),
"execution_id": plan.results[agent.work]["execution_id"] or None,
"workflow_request": plan.text,
"work": agent.work,
}
sources = {
**files,
RECORD: json.dumps({k: v for k, v in record.items() if v is not None}),
}
kept = plan.kept.get(agent.work)
if kept is not None and self._delivery is not None:
# What was kept, as a request naming it in sources_from would have it.
sources = self._delivery.sources(kept)
else:
record = {
"status": "completed",
"customer_case": plan.fields.get("customer_case"),
"execution_id": plan.results[agent.work]["execution_id"] or None,
"workflow_request": plan.text,
"work": agent.work,
}
sources = {
**files,
RECORD: json.dumps({k: v for k, v in record.items() if v is not None}),
}
following = plan.steps[step + 1]
await updater.update_status(
TaskState.TASK_STATE_WORKING,

View File

@@ -134,6 +134,16 @@ class Store:
return None
return target.read_bytes(), media_type(name)
def files(self, tenant: str, case: str, execution_id: str) -> dict[str, str]:
"""Every file kept for an Execution, by name."""
record = self.record(tenant, case, execution_id) or {}
found: dict[str, str] = {}
for name in record.get("files", []):
kept = self.file(tenant, case, execution_id, name)
if kept is not None:
found[name] = kept[0].decode("utf-8")
return found
def case(self, tenant: str, case: str) -> list[dict[str, Any]]:
"""The Customer case's Executions, newest first."""
try: