diff --git a/.agents/plans/README.md b/.agents/plans/README.md index 5727fe9..6aa0dce 100644 --- a/.agents/plans/README.md +++ b/.agents/plans/README.md @@ -7,7 +7,7 @@ One directory per iteration. Each holds the plan for that iteration and, for fin | # | Directory | Status | What it is | | --- | --- | --- | --- | | 1 | `iter-01-execution-engine/` | steps 1 to 6 built on 2026-10-13; 7 planned | The Execution engine: brought from the Reference, given a Workflow, and proved on a toy Workflow and on the Reference's own. | -| 2 | `iter-02-orchestration-engine/` | F1 proposed; F2 and F4 built on 2026-10-20; K1 (ADR-0004) built on 2026-10-21 | The Orchestration engine: routes each request to the agent for its work and relays everything back. | +| 2 | `iter-02-orchestration-engine/` | F1 proposed; F2 and F4 built on 2026-10-20; K1 and K2 (ADR-0004) built on 2026-10-21 | The Orchestration engine: routes each request to the agent for its work and relays everything back. | The plan across both repositories is `../tom_analysis/IMPLEMENTATION_PLAN.md`. diff --git a/.agents/plans/iter-02-orchestration-engine/MAP.md b/.agents/plans/iter-02-orchestration-engine/MAP.md index f81a833..cdd8176 100644 --- a/.agents/plans/iter-02-orchestration-engine/MAP.md +++ b/.agents/plans/iter-02-orchestration-engine/MAP.md @@ -2,7 +2,7 @@ **Iteration:** 2, the Orchestration engine **Intent:** The service every request comes through. It decides which agent the work belongs to, dispatches it, and relays every question and Approval. First behind it: the operating model agent (`../tom_analysis`). -**Status:** F1 proposed; F2 and F4 built 2026-10-20; K1 built 2026-10-21 +**Status:** F1 proposed; F2 and F4 built 2026-10-20; K1 and K2 built 2026-10-21 ## Decided by the owner, 2026-10-20 @@ -26,5 +26,5 @@ | F4 | "Both": architecture, then its files as `sources` to the operating model agent | One request yields both sets of Deliverables under one Customer case | built against scripted agents (`steps/step-4.md`), ahead of F3 at the owner's request; not yet run with real models | | F5 | Later messages to the agent that owns the work | A change to the architecture is followed by a change to the operating model | planned | | K1 | What agents deliver, kept and served at signed links; a platform step given one document of links (ADR-0004, phase 1) | A platform step's output links to each delivered file, and each link serves it | built (`steps/step-K1.md`); the owner's run through the platform to follow | -| K2 | `sources_from`: a request names kept work instead of carrying its files; the sequence moved onto it | An operating model started from the latest architecture of a Customer case | planned | +| K2 | `sources_from`: a request names kept work instead of carrying its files; the sequence moved onto it | An operating model started from the latest architecture of a Customer case | built (`steps/step-K2.md`); the owner's run through the platform to follow | | K3 | Object storage shared with the platform, the platform's sign-in, retention, each file as a platform artifact | A kept guide is listed among the project's artifacts | planned | diff --git a/.agents/plans/iter-02-orchestration-engine/steps/step-K2.md b/.agents/plans/iter-02-orchestration-engine/steps/step-K2.md new file mode 100644 index 0000000..4708768 --- /dev/null +++ b/.agents/plans/iter-02-orchestration-engine/steps/step-K2.md @@ -0,0 +1,25 @@ +# Step K2: building on kept work by reference (ADR-0004, phase 2) + +Built 2026-10-21 on `feat/sources-from`, from `feat/delivery-store`. + +## What was built + +- **`sources_from`:** a request names work kept earlier instead of carrying its files. It may be: + - a link from an earlier document of links, its `record` or its `latest`: what a platform step maps from an earlier step's output. The signature is checked; the link must be of the request's tenant when the request names one, and of its Customer case when it names one; + - `latest/`: the newest completed Execution of that work in the request's Customer case; + - an Execution's id in the request's Customer case. +- **What the agent is sent:** the kept files as `sources`, with the Orchestration engine's record that the work completed (`execution.json`: status, Customer case, Execution, the request, the work). A request naming no Customer case takes the kept work's. +- **Nothing starts, and the caller is told why,** when the reference resolves to nothing, to work that did not end `completed`, to another tenant or Customer case, when the link was changed, when nothing is kept here, or when `sources` is given as well. The reply is a completed task with `{"status": "not_started", "reason": ...}`. +- **The sequence on the same footing:** an agent after another is given what was kept of the one before (`Delivery.sources`), as a request naming it in `sources_from` would be. Without a store, it is given the files relayed, as before. +- **`Store.files`, `Delivery.resolve`, `Delivery.sources`;** the record `execution.json` moved to `delivery.py`. +- **The card** offers `sources_from`. + +## Verified + +- 12 tests in `test_sources_from.py`: each of the three forms; a `latest` link followed to the newest work; a changed link, another tenant, another Customer case, nothing kept, work that ended with warnings, and `sources` with `sources_from` each starting nothing; a sequence's next agent given what was kept; the card. +- 589 tests pass; `ruff` and `mypy` clean. +- Deployed on the local platform; the card offers `sources_from`. No agent was run: the owner runs it through the platform. + +## Using it from the platform + +A second workflow step on the Orchestration engine with `work: operating_model` and `sources_from` mapped from the first step's `record`; or, in a later workflow, `sources_from: latest/solution_architecture` with the Customer case. The operating model agent's own fields (who operates it, business outcomes) go in that step's `scope`. diff --git a/orchestration/card.py b/orchestration/card.py index b73bdff..9489362 100644 --- a/orchestration/card.py +++ b/orchestration/card.py @@ -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/`, " + "or an Execution's id in this Customer case." + ), + }, "deliver": { "type": "string", "enum": ["links", "files"], diff --git a/orchestration/delivery.py b/orchestration/delivery.py index 450be1a..ecdca58 100644 --- a/orchestration/delivery.py +++ b/orchestration/delivery.py @@ -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/`, 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 diff --git a/orchestration/relay.py b/orchestration/relay.py index 765e024..6427220 100644 --- a/orchestration/relay.py +++ b/orchestration/relay.py @@ -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, diff --git a/orchestration/store.py b/orchestration/store.py index b94d4e1..94bda2d 100644 --- a/orchestration/store.py +++ b/orchestration/store.py @@ -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: diff --git a/tests/orchestration/test_sources_from.py b/tests/orchestration/test_sources_from.py new file mode 100644 index 0000000..1647f30 --- /dev/null +++ b/tests/orchestration/test_sources_from.py @@ -0,0 +1,258 @@ +"""A request names work kept earlier instead of carrying its files (ADR-0004, +phase 2): `sources_from` is a link from an earlier document, `latest/`, or +an Execution's id in the request's Customer case.""" + +from __future__ import annotations + +import json +from typing import Any + +from tests.orchestration.test_links import PLATFORM, Harness, document +from tests.orchestration.test_sequence import ScriptedAgents, finished, struct + +GRAPH = '{"elements": []}' + + +def designed(**more: Any) -> ScriptedAgents: + """An architecture agent that has designed once, and an operations agent ready.""" + turns: dict[str, list[Any]] = { + "architecture": [finished("a1", {"graph.json": GRAPH, "guide.md": "# Guide"})], + "operations": [finished("o1", {"model.json": "{}"})], + } + turns.update(more) + return ScriptedAgents(turns) + + +async def design(harness: Harness, case: str = "acme") -> dict[str, Any]: + return document( + await harness.send( + "A landing zone", + {**PLATFORM, "work": "architecture", "customer_case": case}, + ) + ) + + +def not_started(task: dict[str, Any]) -> str: + assert task["status"]["state"] == "TASK_STATE_COMPLETED" + parts = task["status"]["message"]["parts"] + data = next(p["data"] for p in parts if "data" in p) + assert data["status"] == "not_started" + return " ".join(p.get("text", "") for p in parts) + + +def sent_sources(harness: Harness) -> dict[str, Any]: + (message,) = harness.agents.received["operations"] + metadata = struct(message) + assert "sources_from" not in metadata + return metadata + + +async def test_the_latest_work_of_the_case_is_the_agents_sources(tmp_path): + harness = Harness(tmp_path, designed()) + await design(harness) + + await harness.send( + "Operate it", + { + **PLATFORM, + "work": "operations", + "customer_case": "acme", + "sources_from": "latest/architecture", + }, + ) + + sent = sent_sources(harness) + assert sent["sources"]["graph.json"] == GRAPH + assert sent["sources"]["guide.md"] == "# Guide" + assert json.loads(sent["sources"]["execution.json"]) == { + "status": "completed", + "customer_case": "acme", + "execution_id": "a1", + "workflow_request": "A landing zone", + "work": "architecture", + } + + +async def test_a_link_from_an_earlier_document_names_the_work_and_its_case(tmp_path): + # A platform step maps an earlier step's `record` into `sources_from`. + harness = Harness(tmp_path, designed()) + earlier = await design(harness) + + await harness.send( + "Operate it", + {**PLATFORM, "work": "operations", "sources_from": earlier["record"]}, + ) + + sent = sent_sources(harness) + assert sent["customer_case"] == "acme" + assert sent["sources"]["graph.json"] == GRAPH + + +async def test_a_latest_link_is_followed_to_the_newest_completed_work(tmp_path): + harness = Harness( + tmp_path, + designed( + architecture=[ + finished("a1", {"graph.json": "1"}), + finished("a2", {"graph.json": "2"}), + ] + ), + ) + first = await design(harness) + await design(harness) + + await harness.send( + "Operate it", + {**PLATFORM, "work": "operations", "sources_from": first["latest"]}, + ) + + assert sent_sources(harness)["sources"]["graph.json"] == "2" + + +async def test_an_execution_of_the_case_is_named_by_its_id(tmp_path): + harness = Harness(tmp_path, designed()) + await design(harness) + + await harness.send( + "Operate it", + { + **PLATFORM, + "work": "operations", + "customer_case": "acme", + "sources_from": "a1", + }, + ) + + assert sent_sources(harness)["sources"]["graph.json"] == GRAPH + + +async def test_a_link_that_was_changed_starts_nothing(tmp_path): + harness = Harness(tmp_path, designed()) + earlier = await design(harness) + + task = await harness.send( + "Operate it", + { + **PLATFORM, + "work": "operations", + "sources_from": earlier["record"].replace("/a1?", "/a2?"), + }, + ) + + assert "not valid" in not_started(task) + assert harness.agents.received["operations"] == [] + + +async def test_a_link_of_another_tenant_starts_nothing(tmp_path): + harness = Harness(tmp_path, designed()) + earlier = await design(harness) + + task = await harness.send( + "Operate it", + { + **PLATFORM, + "tenant_id": "t2", + "work": "operations", + "sources_from": earlier["record"], + }, + ) + + assert "tenant" in not_started(task) + assert harness.agents.received["operations"] == [] + + +async def test_work_of_another_customer_case_starts_nothing(tmp_path): + harness = Harness(tmp_path, designed()) + earlier = await design(harness) + + task = await harness.send( + "Operate it", + { + **PLATFORM, + "work": "operations", + "customer_case": "other", + "sources_from": earlier["record"], + }, + ) + + assert "acme" in not_started(task) + + +async def test_nothing_kept_to_build_on_starts_nothing(tmp_path): + harness = Harness(tmp_path, designed()) + + task = await harness.send( + "Operate it", + { + **PLATFORM, + "work": "operations", + "customer_case": "acme", + "sources_from": "latest/architecture", + }, + ) + + assert "architecture" in not_started(task) + assert harness.agents.received["operations"] == [] + + +async def test_work_that_ended_with_warnings_is_not_built_on(tmp_path): + harness = Harness( + tmp_path, + designed( + architecture=[ + finished("a1", {"graph.json": GRAPH}, status="completed_with_warnings") + ] + ), + ) + await design(harness) + + task = await harness.send( + "Operate it", + { + **PLATFORM, + "work": "operations", + "customer_case": "acme", + "sources_from": "a1", + }, + ) + + assert "completed_with_warnings" in not_started(task) + + +async def test_sources_and_sources_from_together_start_nothing(tmp_path): + harness = Harness(tmp_path, designed()) + await design(harness) + + task = await harness.send( + "Operate it", + { + **PLATFORM, + "work": "operations", + "customer_case": "acme", + "sources_from": "a1", + "sources": {"x.json": "{}"}, + }, + ) + + assert "sources" in not_started(task) + + +async def test_a_sequence_gives_the_next_agent_what_was_kept(tmp_path): + harness = Harness(tmp_path, designed()) + + await harness.send( + "A landing zone", + {**PLATFORM, "work": "architecture_and_operations", "customer_case": "acme"}, + ) + + sources = sent_sources(harness)["sources"] + assert sources["graph.json"] == GRAPH + assert json.loads(sources["execution.json"])["execution_id"] == "a1" + + +async def test_the_card_offers_sources_from(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] + + assert skill["inputSchema"]["properties"]["sources_from"]["type"] == "string"