spatialagents 0.1.0__py3-none-any.whl

spatialagents/plans.py

@@ -0,0 +1,800 @@
+"""Plans: from a question to a report, with the model asked twice.
+
+A chat loop asks the model at every step. A plan asks it twice -- once to
+**compose** a plan for the goal from what the dataset can support, once to
+**summarise** what the finished run found -- and everything in between is the
+product's deterministic workflow layer: validation, the questions only the
+scientist can answer (decisions), the run, step by step. That is the shape of
+Plexora's decision loop (each model call one structured packet from a cached
+prefix, validated locally, repaired once), applied to a product whose unit of
+work is a deterministic function call.
+
+    run = PlanRun(host, gateway, system=prefix, root=root)
+    run.compose("compare neighbourhoods between responders and non-responders", "cohort")
+    run.answer("d-groupBy", "response")          # the person's answer, never the model's
+    run.confirm_and_run()                        # runs until done, a decision, a failure
+    run.summarise()                              # the report, every sentence checked
+
+**What the product supplies** is a `PlanHost`: the two packets (each `{task,
+input, schema}`), what is accepted from each answer, the plan's view, the
+person's answers and the run. SCIMAP Pro's is `scimappro.ai._harness.plans`
+over its workflow layer; `testing.FakePlanHost` is the reference. The host
+decides everything scientific -- which functions exist, what may run on which
+unit with how many replicates, what a sentence may claim -- and this module
+decides nothing of the kind: it carries packets to the model and answers back.
+
+**Packets.** Each is one call: the host's cached prefix as the system prompt,
+then one user turn -- the packet's input as canonical JSON and the rule
+"answer with one JSON object matching the answer schema" -- with the schema
+reduced to what providers' structured outputs accept (`schema.structured`) and
+the answer read back through `schema.decode`. A bad answer (not JSON, or
+problems the host can name) gets ONE repair: the same conversation, the
+previous answer, and the problems. A compose repair replaces the draft under
+the same plan id (`accept_composed(..., plan_id=)`). A summary is always
+settled, problems or not: the host downgrades what does not hold. A model's bad
+JSON never raises; after its repair the run is `failed` with the reason.
+
+**Decisions are the person's.** `answer` records what the person said through
+the host; no model output ever answers a decision (`resolve` only suggests
+which option a free-text answer meant, for the person to confirm).
+
+**Phases**, persisted in `<root>/<run_id>.json` with atomic writes so
+`PlanRun.resume` continues after a restart:
+
+    composing          a compose packet is out (or paused for credit)
+    awaiting_decision  the plan waits on the person: open decisions, or a checkpoint to continue past
+    validated          ready; the person confirms it to run
+    running            the host is running steps
+    finished           the run is done; the summary is next
+    summarising        a summary packet is out (or paused for credit)
+    reported           the report is written
+    nothing            the goal composed no plan; `summary` says what would answer it
+    failed             `reason` says why
+    stopped            the plan was stopped (an answer, a person, an until_step)
+
+A refusal the gateway pauses on (`gateway.PAUSE_CODES`: credits, caps, a
+provider still down) leaves the phase as it was with `paused` set; `retry()`
+sends the packet again. Events -- composed, problems, decision_needed, step,
+run_finished, report, usage, paused, failed, phase -- go to `on_event` and are
+numbered into `<root>/<run_id>.events.jsonl`, which a page replays.
+`PlanService` drives runs on threads for an HTTP host, one operation per run
+at a time.
+"""
+
+from __future__ import annotations
+
+import json
+import threading
+import time
+from pathlib import Path
+from typing import Protocol
+
+from spatialagents import schema as _schema
+from spatialagents.errors import AgentError
+from spatialagents.gateway import PAUSE_CODES, GatewayError
+from spatialagents.sessions import atomic_write, new_session_id
+from spatialagents.trace import NullTrace
+from spatialagents.wire import ModelRequest, canonical, text_block, with_breakpoints
+
+__all__ = ["CALLING", "PHASES", "PlanHost", "PlanRun", "PlanService", "phase_of"]
+
+TEXT_CAPABILITY = "text_reasoning"
+MAX_TOKENS = 16_000
+PHASES = ("composing", "awaiting_decision", "validated", "running", "finished", "summarising",
+          "reported", "nothing", "failed", "stopped")
+#: Phases in which a model call is out, or would be on `retry()`.
+CALLING = ("composing", "summarising")
+ANSWER_RULE = "Answer with ONE JSON object that matches the answer schema, and nothing else."
+#: How many times `confirm_and_run` asks the host to go on while it reports progress.
+MAX_RUN_CALLS = 200
+
+
+class PlanHost(Protocol):
+    """What a product gives the plan runner. Every method is deterministic."""
+
+    def compose_packet(self, goal: str, dataset: str) -> dict:
+        """`{"task": "plan.compose", "input": dict, "schema": JSON schema}`."""
+        raise NotImplementedError
+
+    def accept_composed(self, goal: str, dataset: str, answer: dict, *, plan_id: str | None = None
+                        ) -> tuple[dict | None, list[dict]]:
+        """`(plan view or None, problems the composer can fix)`. None: the
+        answer composed nothing (`answer["summary"]` says what would answer
+        the goal). With `plan_id` the answer replaces that draft."""
+        raise NotImplementedError
+
+    def plan(self, plan_id: str) -> dict:
+        """The plan's view: id, version, status, steps[], decisions[], next,
+        claim_ceiling, unit_of_replication, n_per_arm, validation."""
+        raise NotImplementedError
+
+    def answer(self, plan_id: str, decision_id: str, value) -> dict:
+        """Record the person's answer to a decision; returns the view."""
+        raise NotImplementedError
+
+    def run(self, plan_id: str, *, confirm: bool = False, from_step=None, until_step=None) -> dict:
+        """Run the plan's pending steps (confirming it first when `confirm`);
+        returns the view and `ran`, the steps this call ran."""
+        raise NotImplementedError
+
+    def summarise_packet(self, plan_id: str) -> dict:
+        """`{"task": "plan.summarise", "input": dict, "schema": JSON schema}`."""
+        raise NotImplementedError
+
+    def accept_summary(self, plan_id: str, answer: dict) -> list[dict]:
+        """What is wrong with a summary's sentences, for one repair."""
+        raise NotImplementedError
+
+    def settle_summary(self, plan_id: str, answer: dict) -> dict:
+        """The report as it will be shown: `{"sentences", "markdown", "path"}`."""
+        raise NotImplementedError
+
+
+class _Paused(Exception):
+    def __init__(self, exc: GatewayError):
+        super().__init__(str(exc))
+        self.exc = exc
+
+
+class _Failed(Exception):
+    """A packet could not be completed; the reason is said, never raised past the run."""
+
+
+def phase_of(view: dict | None, *, confirmed: bool = False) -> str:
+    """The run's phase for a plan in this state."""
+    if not view:
+        return "nothing"
+    status = view.get("status")
+    open_ = [d for d in view.get("decisions") or () if d.get("state") == "open"]
+    if status == "draft":
+        return "awaiting_decision" if open_ else "failed"
+    if status == "validated":
+        return "awaiting_decision" if any(d.get("blocking", True) for d in open_) else "validated"
+    if status in ("confirmed", "running"):
+        return "running"
+    if status == "awaiting_decision":
+        return "awaiting_decision"
+    if status == "done":
+        return "finished"
+    if status in ("failed", "stopped"):
+        return status
+    return "awaiting_decision" if open_ else ("running" if confirmed else "validated")
+
+
+def _problems_text(problems: list) -> str:
+    lines = []
+    for item in problems:
+        where = f"step {item['step']}: " if isinstance(item, dict) and item.get("step") else ""
+        message = item.get("message") if isinstance(item, dict) else str(item)
+        lines.append(f"- {where}{message}")
+    return "\n".join(lines)
+
+
+def _failure_of(view: dict) -> str:
+    for step in view.get("steps") or ():
+        if step.get("status") == "failed":
+            error = step.get("error") or {}
+            message = error.get("message") if isinstance(error, dict) else str(error)
+            return f"step {step.get('id')} ({step.get('function')}) failed: {message}"
+    problems = [p.get("message") for p in (view.get("validation") or {}).get("problems") or ()
+                if isinstance(p, dict) and p.get("blocking")]
+    if problems:
+        return "the plan cannot run: " + "; ".join(str(p) for p in problems[:5])
+    return "the plan cannot run"
+
+
+class PlanRun:
+    """One goal's plan, from compose to report, for one host and one gateway."""
+
+    def __init__(self, host, gateway, *, system: list, root, run_id: str | None = None, on_event=None,
+                 max_repairs: int = 1, capability: str = TEXT_CAPABILITY, max_tokens: int = MAX_TOKENS,
+                 feature: str = "plan", model: str | None = None, trace=None, state: dict | None = None):
+        self.host = host
+        self.gateway = gateway
+        self.system = list(system or [])
+        self.root = Path(root)
+        self.on_event = on_event
+        self.max_repairs = max(0, int(max_repairs))
+        self.capability = capability
+        self.max_tokens = max_tokens
+        self.feature = feature
+        self.model = model
+        self.trace = trace or NullTrace()
+        self._lock = threading.RLock()
+        self._stop_requested = False
+        self.state = state or {
+            "run_id": run_id or new_session_id("pr"), "phase": "composing", "goal": None, "dataset": None,
+            "plan_id": None, "confirmed": False, "summary": None, "reason": None, "paused": None,
+            "packets": [], "usage": {}, "charged_micro": 0, "report": None, "events": 0, "calls": 0,
+            "created_at": time.time()}
+        if state is None:
+            self.trace.start_run(self.run_id, "plan", session_id=self.run_id, capability=capability,
+                                 billing="dev" if getattr(gateway, "dev", False) else "credits")
+
+    # -- identity and persistence --------------------------------------------------
+
+    @property
+    def run_id(self) -> str:
+        return self.state["run_id"]
+
+    @property
+    def phase(self) -> str:
+        return self.state["phase"]
+
+    @property
+    def plan_id(self) -> str | None:
+        return self.state["plan_id"]
+
+    @property
+    def path(self) -> Path:
+        return self.root / f"{self.run_id}.json"
+
+    @property
+    def events_path(self) -> Path:
+        return self.root / f"{self.run_id}.events.jsonl"
+
+    @classmethod
+    def resume(cls, root, run_id: str, host, gateway, **options) -> "PlanRun":
+        """The run as it was saved: its phase, plan, packets and usage."""
+        path = Path(root) / f"{run_id}.json"
+        if not str(run_id).replace("_", "").replace("-", "").isalnum() or not path.is_file():
+            raise AgentError("invalid_input", f"no plan run {run_id!r}")
+        state = json.loads(path.read_text(encoding="utf-8"))
+        return cls(host, gateway, root=root, state=state, **options)
+
+    def _save(self) -> None:
+        with self._lock:
+            self.state["updated_at"] = time.time()
+            atomic_write(self.path, json.dumps(self.state, default=str, ensure_ascii=False))
+
+    def _update(self, **changes) -> None:
+        with self._lock:
+            before = self.state.get("phase")
+            self.state.update(changes)
+            self._save()
+        if changes.get("phase") and changes["phase"] != before:
+            self._emit("phase", phase=changes["phase"], reason=self.state.get("reason"))
+
+    def _emit(self, kind: str, **fields) -> dict:
+        with self._lock:
+            self.state["events"] = int(self.state.get("events") or 0) + 1
+            event = {"seq": self.state["events"], "at": time.time(), "event": kind, "run_id": self.run_id,
+                     **fields}
+            self.events_path.parent.mkdir(parents=True, exist_ok=True)
+            with open(self.events_path, "a", encoding="utf-8") as handle:
+                handle.write(json.dumps(event, default=str, ensure_ascii=False) + "\n")
+            atomic_write(self.path, json.dumps(self.state, default=str, ensure_ascii=False))
+        if self.on_event is not None:
+            self.on_event(event)
+        return event
+
+    def events(self, after: int = 0) -> list:
+        """The run's events with `seq > after`, oldest first."""
+        if not self.events_path.is_file():
+            return []
+        out = []
+        for line in self.events_path.read_text(encoding="utf-8").splitlines():
+            try:
+                event = json.loads(line)
+            except ValueError:
+                continue
+            if int(event.get("seq") or 0) > after:
+                out.append(event)
+        return out
+
+    # -- what a caller is shown ----------------------------------------------------------
+
+    def view(self) -> dict | None:
+        return self.host.plan(self.plan_id) if self.plan_id else None
+
+    def actions(self, view: dict | None = None) -> list:
+        """What the person can do now: answer, confirm, continue, summarise, retry, compose."""
+        phase = self.phase
+        if self.state.get("paused"):
+            return ["retry"]
+        if phase == "awaiting_decision":
+            view = view if view is not None else self.view()
+            open_ = [d for d in (view or {}).get("decisions") or () if d.get("state") == "open"]
+            if open_:
+                return ["answer"]
+            return ["continue"] if self.state.get("confirmed") else ["confirm"]
+        if phase == "validated":
+            return ["confirm"]
+        if phase == "finished":
+            return ["summarise"]
+        if phase == "stopped" and self.state.get("confirmed"):
+            return ["continue"]
+        if phase in ("nothing", "failed"):
+            return ["compose"]
+        return []
+
+    def status(self) -> dict:
+        view = self.view() if self.plan_id else None
+        keep = ("run_id", "phase", "goal", "dataset", "plan_id", "confirmed", "summary", "reason", "paused",
+                "usage", "charged_micro", "report", "created_at", "updated_at")
+        out = {key: self.state.get(key) for key in keep}
+        out["charged_credits"] = round(int(self.state.get("charged_micro") or 0) / 10_000, 2)
+        out["packets"] = [{k: p.get(k) for k in ("kind", "task", "attempts", "repaired", "ok", "problems",
+                                                   "gateway_request_id", "charged_micro")}
+                          for p in self.state.get("packets") or ()]
+        out["plan"] = view
+        out["actions"] = self.actions(view)
+        return out
+
+    # -- the model -----------------------------------------------------------------------
+
+    def _call(self, kind: str, packet: dict, messages: list):
+        """One packet call: `(answer or None, text, problem or None)`. Raises
+        `_Paused` on a refusal the run waits out and `_Failed` on any other."""
+        with self._lock:
+            # Every call gets a key of its own, a refused one included: the
+            # gateway frees a key only for what never reached a provider.
+            number = self.state["calls"] = int(self.state.get("calls") or 0) + 1
+            self._save()
+        source = packet.get("schema") or {}
+        context = {"feature": self.feature, "agent": "plan", "workflow": "plan", "session_id": self.run_id,
+                   "attempt": 1}
+        request = ModelRequest(capability=self.capability, system=self.system,
+                               messages=with_breakpoints(messages), max_tokens=self.max_tokens,
+                               output_schema=_schema.structured(source) if source else None,
+                               context=context, model=self.model, task=packet.get("task"))
+        try:
+            response = self.gateway.messages(request, idempotency_key=f"{self.run_id}.{kind}.{number}")
+        except GatewayError as exc:
+            if exc.code in PAUSE_CODES:
+                raise _Paused(exc) from None
+            raise _Failed(f"the model call was refused: {exc.code}: {exc}") from None
+        record = {"kind": kind, "task": packet.get("task"), "gateway_request_id": response.gateway_request_id,
+                  "attempts": response.attempts, "repaired": kind.endswith("repair"),
+                  "charged_micro": response.charged_micro, "model": response.model,
+                  "usage": {name: getattr(response.usage, name) for name in response.usage.__dataclass_fields__},
+                  "at": time.time()}
+        problem = None
+        answer = None
+        try:
+            value = response.json()
+            if not isinstance(value, dict):
+                raise ValueError("not an object")
+            answer = _schema.decode(value, source) if source else value
+        except ValueError:
+            problem = "the reply was not one JSON object"
+        record["ok"] = problem is None
+        with self._lock:
+            self.state.setdefault("packets", []).append(record)
+            self.state["charged_micro"] = int(self.state.get("charged_micro") or 0) + response.charged_micro
+            usage = self.state.setdefault("usage", {})
+            for name, value in record["usage"].items():
+                usage[name] = int(usage.get(name) or 0) + int(value or 0)
+            self._save()
+        self.trace.call(self.run_id, worker=0, seq=number, kind=kind, packet_id=kind, capability=self.capability,
+                        task=packet.get("task"), model=response.model, provider=response.provider,
+                        input_uncached=response.usage.input_uncached, cache_read=response.usage.cache_read,
+                        cache_write=response.usage.cache_write, output_tokens=response.usage.output_tokens,
+                        price_micro=response.price_micro, charged_micro=response.charged_micro,
+                        cost_micro=response.cost_micro, gateway_request_id=response.gateway_request_id,
+                        latency_ms=response.latency_ms, valid=problem is None, attempts=response.attempts,
+                        problem=problem)
+        self._emit("usage", packet=kind, charged_micro=response.charged_micro,
+                   total_charged_micro=self.state["charged_micro"], input_tokens=response.usage.input_total,
+                   cache_read=response.usage.cache_read, output_tokens=response.usage.output_tokens)
+        return answer, response.text, problem
+
+    @staticmethod
+    def _turn(packet: dict) -> dict:
+        return {"role": "user", "content": [text_block(canonical(packet.get("input") or {}) + "\n\n"
+                                                       + ANSWER_RULE)]}
+
+    @staticmethod
+    def _repair_turns(messages: list, text: str, problems: list) -> list:
+        said = (text or "").strip() or "(no answer)"
+        return messages + [
+            {"role": "assistant", "content": [text_block(said[:20_000])]},
+            {"role": "user", "content": [text_block(
+                "That answer has problems:\n" + _problems_text(problems)
+                + "\nAnswer again with ONE corrected JSON object for the same packet, and nothing else.")]}]
+
+    def _paused(self, exc: GatewayError) -> dict:
+        self._update(paused={"code": exc.code, "message": str(exc)})
+        self._emit("paused", code=exc.code, message=str(exc),
+                   resume="retry once the account can pay for it (or the provider is back)")
+        return self.status()
+
+    def _fail(self, reason: str) -> dict:
+        self._update(phase="failed", reason=reason, paused=None)
+        self._emit("failed", reason=reason)
+        self.trace.finish_run(self.run_id, "failed", {"reason": reason})
+        return self.status()
+
+    # -- compose ---------------------------------------------------------------------------
+
+    def compose(self, goal: str, dataset: str) -> dict:
+        """Compose a plan for `goal` on `dataset`: one packet, one repair at most."""
+        self._update(phase="composing", goal=goal, dataset=dataset, reason=None, paused=None, plan_id=None,
+                     confirmed=False, summary=None, report=None)
+        try:
+            packet = self.host.compose_packet(goal, dataset)
+        except Exception as exc:              # noqa: BLE001 -- the run says why
+            return self._fail(f"the compose packet could not be built: {type(exc).__name__}: {exc}")
+        messages = [self._turn(packet)]
+        plan_id = None
+        view = None
+        answer = None
+        problems: list = []
+        for attempt in range(self.max_repairs + 1):
+            kind = "compose" if attempt == 0 else "compose_repair"
+            try:
+                answer, text, problem = self._call(kind, packet, messages)
+            except _Paused as paused:
+                return self._paused(paused.exc)
+            except _Failed as failed:
+                return self._fail(str(failed))
+            if problem is not None:
+                problems = [{"kind": "format", "message": problem, "blocking": True}]
+            else:
+                try:
+                    view, problems = self.host.accept_composed(goal, dataset, answer, plan_id=plan_id)
+                except Exception as exc:      # noqa: BLE001 -- a host refusal is a reason, not a crash
+                    return self._fail(f"the composed plan was refused: {type(exc).__name__}: {exc}")
+                problems = list(problems or [])
+                if view:
+                    plan_id = view.get("id") or plan_id
+            if not problems:
+                break
+            self._mark_problems(problems)
+            self._emit("problems", packet="compose", attempt=attempt + 1, problems=problems)
+            if attempt < self.max_repairs:
+                messages = self._repair_turns(messages, text, problems)
+        summary = (answer or {}).get("summary") if isinstance(answer, dict) else None
+        if problems:
+            self._update(plan_id=plan_id, summary=summary)
+            return self._fail("the composed plan still has problems after a repair: "
+                              + "; ".join(str(p.get("message")) for p in problems[:5]))
+        if not view:
+            self._update(phase="nothing", plan_id=None, summary=summary, paused=None)
+            self._emit("composed", plan_id=None, summary=summary)
+            self.trace.finish_run(self.run_id, "nothing", {"summary": summary})
+            return self.status()
+        phase = phase_of(view)
+        reason = _failure_of(view) if phase == "failed" else None
+        self._update(plan_id=view.get("id"), summary=summary, paused=None, reason=reason)
+        self._emit("composed", plan_id=view.get("id"), summary=summary, status=view.get("status"),
+                   steps=len(view.get("steps") or ()))
+        self._settle_phase(view, phase)
+        return self.status()
+
+    def _mark_problems(self, problems: list) -> None:
+        with self._lock:
+            if self.state.get("packets"):
+                self.state["packets"][-1]["problems"] = len(problems)
+                self._save()
+
+    def _settle_phase(self, view: dict, phase: str | None = None) -> None:
+        phase = phase or phase_of(view, confirmed=self.state.get("confirmed"))
+        reason = _failure_of(view) if phase == "failed" else None
+        self._update(phase=phase, reason=reason)
+        if phase == "awaiting_decision":
+            for decision in view.get("decisions") or ():
+                if decision.get("state") == "open":
+                    self._emit("decision_needed", plan_id=view.get("id"), decision=decision)
+        elif phase == "failed":
+            self._emit("failed", reason=reason)
+
+    # -- the person -----------------------------------------------------------------------
+
+    def answer(self, decision_id: str, value) -> dict:
+        """The person's answer to one decision (through the host, which
+        validates it); returns the run's status."""
+        self._require_plan()
+        view = self.host.answer(self.plan_id, decision_id, value)
+        self._emit("answered", decision_id=decision_id, answer=value)
+        if self.phase not in ("running", "summarising"):
+            self._settle_phase(view)
+        return self.status()
+
+    def resolve(self, decision_id: str, text: str) -> dict:
+        """Which option a free-text answer means: one small packet. It only
+        suggests -- `{"option", "why"}`, option None when none fits -- and the
+        person confirms it with `answer`."""
+        self._require_plan()
+        decision = next((d for d in (self.view() or {}).get("decisions") or () if d.get("id") == decision_id),
+                        None)
+        if decision is None or not decision.get("options"):
+            raise AgentError("invalid_input", f"decision {decision_id!r} has no options to match")
+        ids = [str(o.get("id")) for o in decision["options"] if isinstance(o, dict) and o.get("id") is not None]
+        packet = {"task": "plan.resolve",
+                  "input": {"question": decision.get("question"), "options": decision["options"],
+                            "answer": str(text)[:2000],
+                            "instructions": "Which option did the person mean? null when none of them."},
+                  "schema": {"type": "object", "properties": {
+                      "option": {"anyOf": [{"type": "string", "enum": ids}, {"type": "null"}]},
+                      "why": {"type": "string"}}, "required": ["option", "why"]}}
+        try:
+            answer, _text, problem = self._call("resolve", packet, [self._turn(packet)])
+        except _Paused as paused:
+            self._paused(paused.exc)
+            return {"option": None, "why": f"paused: {paused.exc.code}"}
+        except _Failed as failed:
+            return {"option": None, "why": str(failed)}
+        if problem or answer.get("option") not in ids:
+            return {"option": None, "why": (answer or {}).get("why") or problem or "no option matched"}
+        return {"option": answer["option"], "why": str(answer.get("why") or "")}
+
+    def stop(self, reason: str = "stopped by the person") -> dict:
+        """Stop: nothing more runs until the person continues. A run cannot
+        be cancelled mid-step; one in progress stops after the host's current
+        call returns."""
+        if self.phase == "running":
+            self._stop_requested = True
+            self._emit("stop_requested", reason=reason)
+            return self.status()
+        self._update(phase="stopped", reason=reason)
+        self._emit("stopped", reason=reason)
+        return self.status()
+
+    def _require_plan(self) -> None:
+        if not self.plan_id:
+            raise AgentError("invalid_input", "this plan run has no plan", detail={"phase": self.phase})
+
+    # -- running ---------------------------------------------------------------------------
+
+    def confirm_and_run(self) -> dict:
+        """The person agreed: confirm the plan and run it until it is done,
+        waits on a decision (a checkpoint returns control to the person),
+        fails or stops."""
+        return self._run(confirm=True)
+
+    def continue_run(self, *, from_step=None, until_step=None) -> dict:
+        """Go on after a checkpoint (or a stop), or rerun from a step."""
+        if not self.state.get("confirmed"):
+            raise AgentError("invalid_input", "the plan has not been confirmed; confirm_and_run first")
+        return self._run(confirm=False, from_step=from_step, until_step=until_step)
+
+    def _run(self, *, confirm: bool, from_step=None, until_step=None) -> dict:
+        self._require_plan()
+        previous = self.phase
+        self._stop_requested = False
+        self._update(phase="running", reason=None)
+        view = None
+        try:
+            for call in range(MAX_RUN_CALLS):
+                if self._stop_requested:
+                    break
+                view = self.host.run(self.plan_id, confirm=confirm and call == 0,
+                                     from_step=from_step if call == 0 else None,
+                                     until_step=until_step)
+                if call == 0 and confirm:
+                    self.state["confirmed"] = True
+                    self._save()
+                for ran in view.get("ran") or ():
+                    self._emit("step", plan_id=self.plan_id, **{k: v for k, v in ran.items() if k != "event"})
+                if view.get("status") not in ("confirmed", "running") or not view.get("ran"):
+                    break
+        except Exception:
+            self._update(phase=previous)
+            raise
+        status = view.get("status") if view else None
+        if self._stop_requested:
+            self._stop_requested = False
+            self._update(phase="stopped", reason="stopped by the person")
+            self._emit("stopped", reason="stopped by the person")
+            return self.status()
+        if status in ("confirmed", "running"):
+            self._update(phase="stopped", reason="the run made no further progress")
+            return self.status()
+        phase = phase_of(view, confirmed=True)
+        if phase == "finished":
+            self._update(phase="finished")
+            self._emit("run_finished", plan_id=self.plan_id, status=status)
+        elif phase == "stopped":
+            self._update(phase="stopped", reason=view.get("reason") or "the plan stopped")
+            self._emit("run_finished", plan_id=self.plan_id, status=status)
+        else:
+            self._settle_phase(view, phase)
+            if phase == "failed":
+                self._emit("run_finished", plan_id=self.plan_id, status=status)
+        return self.status()
+
+    # -- the summary ---------------------------------------------------------------------------
+
+    def summarise(self) -> dict:
+        """The report: one packet, one repair at most, then settled by the host."""
+        self._require_plan()
+        self._update(phase="summarising", reason=None, paused=None)
+        try:
+            packet = self.host.summarise_packet(self.plan_id)
+        except Exception as exc:              # noqa: BLE001 -- the run says why
+            return self._fail(f"the summary packet could not be built: {type(exc).__name__}: {exc}")
+        messages = [self._turn(packet)]
+        settled_on = None
+        for attempt in range(self.max_repairs + 1):
+            kind = "summarise" if attempt == 0 else "summarise_repair"
+            try:
+                answer, text, problem = self._call(kind, packet, messages)
+            except _Paused as paused:
+                return self._paused(paused.exc)
+            except _Failed as failed:
+                return self._fail(str(failed))
+            if problem is not None:
+                problems = [{"kind": "format", "message": problem}]
+            else:
+                settled_on = answer
+                try:
+                    problems = list(self.host.accept_summary(self.plan_id, answer) or [])
+                except Exception as exc:      # noqa: BLE001 -- the host settles what it can
+                    problems = []
+                    self._emit("problems", packet="summarise", attempt=attempt + 1,
+                               problems=[{"message": f"{type(exc).__name__}: {exc}"}])
+            if not problems:
+                break
+            self._mark_problems(problems)
+            self._emit("problems", packet="summarise", attempt=attempt + 1, problems=problems)
+            if attempt < self.max_repairs:
+                messages = self._repair_turns(messages, text, problems)
+        if settled_on is None:
+            return self._fail("the summary was not one JSON object, twice")
+        try:
+            report = self.host.settle_summary(self.plan_id, settled_on)
+        except Exception as exc:              # noqa: BLE001 -- the run says why
+            return self._fail(f"the summary could not be settled: {type(exc).__name__}: {exc}")
+        self._update(phase="reported", report={"path": report.get("path"),
+                                               "sentences": len(report.get("sentences") or ())})
+        self._emit("report", plan_id=self.plan_id, path=report.get("path"), markdown=report.get("markdown"),
+                   sentences=report.get("sentences"))
+        self.trace.finish_run(self.run_id, "reported", {"plan_id": self.plan_id,
+                                                        "charged_micro": self.state.get("charged_micro")})
+        return {**self.status(), "markdown": report.get("markdown"), "sentences": report.get("sentences")}
+
+    # -- after a pause or a restart --------------------------------------------------------------
+
+    def retry(self) -> dict:
+        """Send the packet a pause (or a restart) interrupted again."""
+        if self.phase == "composing":
+            return self.compose(self.state["goal"], self.state["dataset"])
+        if self.phase == "summarising":
+            return self.summarise()
+        raise AgentError("invalid_input", f"nothing to retry in phase {self.phase!r}")
+
+    def refresh(self) -> dict:
+        """Read the plan again (it may have been edited elsewhere) and settle the phase."""
+        view = self.view()
+        if view is not None and self.phase not in CALLING:
+            self._settle_phase(view)
+        return self.status()
+
+
+class PlanService:
+    """Every plan run one process drives, for an HTTP host: a model call or a
+    run goes on a thread and returns at once; `events` is a held poll.
+
+    `host_factory()` gives the product's `PlanHost`, `gateway_factory()` its
+    gateway client, `system` the cached prefix (or a function returning it)."""
+
+    def __init__(self, root, *, host_factory, gateway_factory, system, trace=None, run_options: dict | None = None):
+        self.root = Path(root)
+        self.host_factory = host_factory
+        self.gateway_factory = gateway_factory
+        self._system = system
+        self.trace = trace
+        self.run_options = dict(run_options or {})
+        self._runs: dict = {}
+        self._threads: dict = {}
+        self._lock = threading.Lock()
+        self._cond = threading.Condition()
+
+    def _notify(self, event: dict) -> None:
+        with self._cond:
+            self._cond.notify_all()
+
+    def system(self) -> list:
+        return self._system() if callable(self._system) else list(self._system or [])
+
+    def _options(self) -> dict:
+        return {"system": self.system(), "on_event": self._notify, "trace": self.trace, **self.run_options}
+
+    def run(self, run_id: str) -> PlanRun:
+        with self._lock:
+            found = self._runs.get(run_id)
+        if found is None:
+            found = PlanRun.resume(self.root, run_id, self.host_factory(), self.gateway_factory(),
+                                   **self._options())
+            with self._lock:
+                found = self._runs.setdefault(run_id, found)
+        return found
+
+    def busy(self, run_id: str) -> bool:
+        with self._lock:
+            thread = self._threads.get(run_id)
+        return bool(thread and thread.is_alive())
+
+    def _background(self, run: PlanRun, work) -> dict:
+        with self._lock:
+            thread = self._threads.get(run.run_id)
+            if thread and thread.is_alive():
+                raise AgentError("conflict", "this plan is still working on the last request",
+                                 detail={"phase": run.phase}, retryable=True)
+
+            def body():
+                try:
+                    work()
+                except Exception as exc:      # noqa: BLE001 -- the run's events say why
+                    run._emit("error", code=getattr(exc, "code", "internal_error"),
+                              message=f"{type(exc).__name__}: {exc}")
+                finally:
+                    self._notify({})
+
+            thread = threading.Thread(target=body, name=f"spatialagents-plan-{run.run_id}", daemon=True)
+            self._threads[run.run_id] = thread
+            thread.start()
+        return {"run_id": run.run_id, "running": True, "phase": run.phase}
+
+    def start(self, goal: str, dataset: str) -> dict:
+        run = PlanRun(self.host_factory(), self.gateway_factory(), root=self.root, **self._options())
+        run._save()
+        with self._lock:
+            self._runs[run.run_id] = run
+        return self._background(run, lambda: run.compose(goal, dataset))
+
+    def answer(self, run_id: str, decision_id: str, value) -> dict:
+        run = self.run(run_id)
+        if self.busy(run_id):
+            raise AgentError("conflict", "this plan is still working; answer once it waits for you",
+                             retryable=True)
+        return run.answer(decision_id, value)
+
+    def resolve(self, run_id: str, decision_id: str, text: str) -> dict:
+        return self.run(run_id).resolve(decision_id, text)
+
+    def confirm(self, run_id: str) -> dict:
+        run = self.run(run_id)
+        return self._background(run, run.confirm_and_run)
+
+    def proceed(self, run_id: str, *, from_step=None, until_step=None) -> dict:
+        run = self.run(run_id)
+        return self._background(run, lambda: run.continue_run(from_step=from_step, until_step=until_step))
+
+    def summarise(self, run_id: str) -> dict:
+        run = self.run(run_id)
+        return self._background(run, run.summarise)
+
+    def retry(self, run_id: str) -> dict:
+        run = self.run(run_id)
+        return self._background(run, run.retry)
+
+    def stop(self, run_id: str) -> dict:
+        return self.run(run_id).stop()
+
+    def status(self, run_id: str) -> dict:
+        return {**self.run(run_id).status(), "running": self.busy(run_id)}
+
+    def wait(self, run_id: str, timeout: float | None = None) -> bool:
+        with self._lock:
+            thread = self._threads.get(run_id)
+        if thread is None:
+            return True
+        thread.join(timeout)
+        return not thread.is_alive()
+
+    def events(self, run_id: str, after: int = 0, wait_s: float = 0.0) -> dict:
+        run = self.run(run_id)
+        deadline = time.monotonic() + max(0.0, min(float(wait_s or 0), 25.0))
+        with self._cond:
+            while True:
+                found = run.events(after)
+                remaining = deadline - time.monotonic()
+                if found or remaining <= 0 or not (self.busy(run_id) or wait_s):
+                    break
+                self._cond.wait(min(remaining, 1.0))
+        return {"run_id": run_id, "events": found, "after": found[-1]["seq"] if found else after,
+                "running": self.busy(run_id), "phase": run.phase}
+
+    def list(self, limit: int = 50) -> list:
+        out = []
+        for path in sorted(self.root.glob("*.json"), key=lambda p: p.stat().st_mtime, reverse=True)[:limit]:
+            try:
+                state = json.loads(path.read_text(encoding="utf-8"))
+            except (OSError, ValueError):
+                continue
+            out.append({k: state.get(k) for k in ("run_id", "phase", "goal", "dataset", "plan_id",
+                                                  "charged_micro", "created_at")})
+        return out
+