agent-instruction-protocol 0.7.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
aip/client/server.py ADDED
@@ -0,0 +1,219 @@
1
+ """The client's side of the HTTP API (design §4.1, §8): where the server is, how to call
2
+ it, and the catalog operations `aip search|list|publish|get|pin|retire` are built on.
3
+
4
+ `Server(url, token)` is one HTTP session with the bearer token attached and the error
5
+ envelope turned into `ServerError`. Where the client points comes from `settings()`:
6
+ `AIP_SERVER` and `AIP_TOKEN` override `~/.config/aip/config.json` (`aip config` writes
7
+ it); nothing configured means local folders only.
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ import hashlib
13
+ import io
14
+ import json
15
+ import os
16
+ import shutil
17
+ import tarfile
18
+ import tempfile
19
+ from pathlib import Path
20
+ from typing import Any, Dict, List
21
+
22
+ from aip.errors import AipError
23
+
24
+ JSON = Dict[str, Any]
25
+ MANIFEST = ".aip-manifest.json"
26
+
27
+
28
+ # -------------------------------------------------------------------------- config
29
+
30
+
31
+ def config_path() -> Path:
32
+ override = os.environ.get("AIP_CONFIG")
33
+ return Path(override) if override else Path.home() / ".config" / "aip" / "config.json"
34
+
35
+
36
+ def load_config() -> JSON:
37
+ path = config_path()
38
+ if not path.is_file():
39
+ return {}
40
+ try:
41
+ data = json.loads(path.read_text())
42
+ except (OSError, ValueError):
43
+ return {}
44
+ return data if isinstance(data, dict) else {}
45
+
46
+
47
+ def save_config(config: JSON) -> Path:
48
+ path = config_path()
49
+ path.parent.mkdir(parents=True, exist_ok=True)
50
+ path.write_text(json.dumps(config, indent=2) + "\n")
51
+ try:
52
+ path.chmod(0o600) # it may hold the token
53
+ except OSError:
54
+ pass
55
+ return path
56
+
57
+
58
+ def settings() -> JSON:
59
+ """`{"server", "token", "source"}`: the environment first, then the config file."""
60
+ config = load_config()
61
+ server = os.environ.get("AIP_SERVER") or config.get("server") or None
62
+ token = os.environ.get("AIP_TOKEN") or config.get("token") or None
63
+ source = "AIP_SERVER" if os.environ.get("AIP_SERVER") else (str(config_path()) if config.get("server") else None)
64
+ return {"server": server, "token": token, "source": source}
65
+
66
+
67
+ def configured() -> "Server | None":
68
+ """The server the client points at, or None when none is configured."""
69
+ s = settings()
70
+ return Server(s["server"], s["token"]) if s["server"] else None
71
+
72
+
73
+ # -------------------------------------------------------------------------- errors
74
+
75
+
76
+ class ServerError(AipError):
77
+ """A failed call: the server's error envelope, or no server to speak of."""
78
+
79
+ def __init__(self, status: int, kind: str, message: str, location: str | None = None, **extra: Any):
80
+ super().__init__(message, kind)
81
+ self.status, self.location, self.extra = status, location, extra
82
+
83
+ def __str__(self) -> str:
84
+ where = f" at {self.location}" if self.location else ""
85
+ return f"{self.kind}{where}: {self.message}"
86
+
87
+
88
+ # ------------------------------------------------------------------------- the server
89
+
90
+
91
+ class Server:
92
+ """One HTTP session against an AIP server. `session` is any httpx-style client (FastAPI's
93
+ test client qualifies); by default a real one on `url`."""
94
+
95
+ def __init__(self, url: str, token: str | None = None, session: Any = None):
96
+ self.url = url.rstrip("/")
97
+ self.token = token
98
+ if session is None:
99
+ import httpx
100
+
101
+ session = httpx.Client(base_url=self.url, timeout=httpx.Timeout(None, connect=10.0))
102
+ self._session = session
103
+
104
+ def request(self, method: str, path: str, **kwargs: Any):
105
+ import httpx
106
+
107
+ headers = dict(kwargs.pop("headers", {}) or {})
108
+ if self.token:
109
+ headers["Authorization"] = f"Bearer {self.token}"
110
+ try:
111
+ response = self._session.request(method, path, headers=headers, **kwargs)
112
+ except httpx.HTTPError as exc:
113
+ raise ServerError(0, "unreachable", f"{self.url}: {exc}") from exc
114
+ if response.status_code >= 400:
115
+ raise self._error(response)
116
+ return response
117
+
118
+ @staticmethod
119
+ def _error(response) -> ServerError:
120
+ try:
121
+ error = response.json()["error"]
122
+ return ServerError(response.status_code, error.pop("kind"), error.pop("message"),
123
+ error.pop("location", None), **error)
124
+ except (ValueError, KeyError, TypeError, AttributeError):
125
+ return ServerError(response.status_code, "http_error", f"HTTP {response.status_code}: {response.text[:200]}")
126
+
127
+ def get(self, path: str, **params: Any) -> Any:
128
+ return self.request("GET", path, params={k: v for k, v in params.items() if v is not None}).json()
129
+
130
+ def post(self, path: str, body: JSON | None = None) -> Any:
131
+ return self.request("POST", path, json=body or {}).json()
132
+
133
+ def bytes(self, path: str, **params: Any) -> bytes:
134
+ return self.request("GET", path, params={k: v for k, v in params.items() if v is not None}).content
135
+
136
+ # ------------------------------------------------------------------ catalog
137
+
138
+ def search(self, query: str, limit: int = 10) -> List[JSON]:
139
+ return self.get("/catalog/search", q=query, limit=limit)
140
+
141
+ def list(self) -> List[JSON]:
142
+ return self.get("/catalog")
143
+
144
+ def info(self, ref: str) -> JSON:
145
+ return self.get(f"/catalog/{ref}")
146
+
147
+ def file(self, ref: str, path: str) -> bytes:
148
+ return self.bytes(f"/catalog/{ref}/files/{path}")
149
+
150
+ def capabilities(self, ref: str) -> JSON:
151
+ return self.get(f"/procedures/{ref}/capabilities")
152
+
153
+ def pin(self, name: str, revision: str | None) -> JSON:
154
+ return self.post(f"/catalog/{name}/pin", {"revision": revision})
155
+
156
+ def retire(self, name: str, revision: str) -> JSON:
157
+ return self.post(f"/catalog/{name}/retire", {"revision": revision})
158
+
159
+ def runs(self, name: str | None = None, status: str | None = None, limit: int = 50) -> List[JSON]:
160
+ return self.get("/runs", name=name, status=status, limit=limit)
161
+
162
+ def run(self, run_id: str) -> JSON:
163
+ return self.get(f"/runs/{run_id}")
164
+
165
+ # --------------------------------------------------------------- transfers
166
+
167
+ def publish(self, folder: Path) -> JSON:
168
+ """Upload every file of a skill folder; the server validates and returns `{name, revision, ...}`.
169
+ Validate locally first (`aip publish` does) so a rejection is never a surprise."""
170
+ from aip.server.app import upload_of
171
+
172
+ return self.post("/catalog", upload_of(Path(folder)))
173
+
174
+ def download(self, ref: str, out_dir: Path) -> Path:
175
+ """Fetch a revision losslessly to `<out_dir>/<name>/`: the tar of every file plus its
176
+ manifest, modes restored from the manifest, every file hashed against it (the first
177
+ mismatch aborts, naming the file), and the revision recomputed. Refuses to overwrite."""
178
+ from aip.server.records import revision, walk
179
+
180
+ out_dir = Path(out_dir)
181
+ out_dir.mkdir(parents=True, exist_ok=True)
182
+ data = self.bytes(f"/catalog/{ref}/files", archive="tar")
183
+ tmp = Path(tempfile.mkdtemp(prefix=".aip-get-", dir=out_dir))
184
+ try:
185
+ with tarfile.open(fileobj=io.BytesIO(data)) as tar:
186
+ tar.extractall(tmp, filter="data")
187
+ manifest_path = tmp / MANIFEST
188
+ if not manifest_path.is_file():
189
+ raise ServerError(0, "bad_archive", f"{ref}: the archive carries no {MANIFEST}")
190
+ manifest = json.loads(manifest_path.read_text())
191
+ name, expected = manifest["name"], manifest["revision"]
192
+ folder = tmp / name
193
+ if not folder.is_dir():
194
+ raise ServerError(0, "bad_archive", f"{ref}: the archive has no {name}/ folder")
195
+ for entry in sorted(manifest["files"], key=lambda e: e["path"]):
196
+ path = folder / entry["path"]
197
+ if not path.is_file():
198
+ raise ServerError(0, "hash_mismatch", f"{name}/{entry['path']}: missing from the archive",
199
+ location=entry["path"])
200
+ path.chmod(int(entry["mode"]) & 0o777)
201
+ digest = hashlib.sha256(path.read_bytes()).hexdigest()
202
+ if digest != entry["sha256"]:
203
+ raise ServerError(0, "hash_mismatch",
204
+ f"{name}/{entry['path']}: sha256 {digest[:12]}… does not match the manifest's "
205
+ f"{entry['sha256'][:12]}…", location=entry["path"])
206
+ files, _ = walk(folder)
207
+ if revision(files) != expected:
208
+ raise ServerError(0, "hash_mismatch", f"{name}: the files on disk hash to {revision(files)}, "
209
+ f"not the manifest's {expected}")
210
+ target = out_dir / name
211
+ if target.exists():
212
+ raise ServerError(0, "exists", f"{target} already exists; choose another --out or remove it")
213
+ shutil.move(str(folder), str(target))
214
+ return target
215
+ finally:
216
+ shutil.rmtree(tmp, ignore_errors=True)
217
+
218
+
219
+ __all__ = ["Server", "ServerError", "config_path", "configured", "load_config", "save_config", "settings"]
aip/db/__init__.py ADDED
@@ -0,0 +1 @@
1
+ """Database projections of AIP skills. Neo4j today: `aip.db.neo4j`."""
aip/db/neo4j.py ADDED
@@ -0,0 +1,58 @@
1
+ """Compatibility shim for the 0.4 `aip db` API over the Neo4j backend.
2
+
3
+ The projection itself lives in `aip.server.backends.neo4j` (graph shape, Cypher,
4
+ `Neo4jBackend`); the records and the folder <-> record conversions in
5
+ `aip.server.records`. This module keeps the four functions `aip db` and older callers
6
+ use, each opening a backend for the call:
7
+
8
+ - `load(skill_dir)`: validate, snapshot, publish; returns `name@revision`.
9
+ - `fetch(name, revision=None)`: the record as JSON (files with bytes), or None.
10
+ - `export(name, out_dir, revision=None)`: rebuild the folder at `out_dir/<name>`, hash-verified.
11
+ - `list_skills()`: one row per revision, newest first per name.
12
+
13
+ `Bundle` stays as an alias of `SkillRecord`, and `Connection` is re-exported.
14
+ """
15
+
16
+ from __future__ import annotations
17
+
18
+ from pathlib import Path
19
+ from typing import Any, Dict, List
20
+
21
+ from aip.server.backend import NotFound
22
+ from aip.server.backends.neo4j import Connection, Neo4jBackend # noqa: F401
23
+ from aip.server.records import (IGNORE_DIRS, IGNORE_FILES, IGNORE_SUFFIXES, FileRecord, SkillRecord, # noqa: F401
24
+ materialize, snapshot, write_files)
25
+
26
+ JSON = Dict[str, Any]
27
+
28
+ Bundle = SkillRecord
29
+
30
+
31
+ def load(skill_dir: Path, conn: Connection | None = None) -> str:
32
+ """Validate, snapshot, and publish a skill. Returns the skill id (`name@revision`)."""
33
+ record = snapshot(skill_dir)
34
+ with Neo4jBackend(conn) as backend:
35
+ backend.catalog.publish(record)
36
+ return record.id
37
+
38
+
39
+ def fetch(name: str, revision: str | None = None, conn: Connection | None = None) -> JSON | None:
40
+ """The resolved (or named) revision as JSON, files included; None when there is no such skill."""
41
+ with Neo4jBackend(conn) as backend:
42
+ try:
43
+ return backend.catalog.get(name, revision).to_json()
44
+ except NotFound:
45
+ return None
46
+
47
+
48
+ def export(name: str, out_dir: Path, revision: str | None = None, conn: Connection | None = None) -> Path:
49
+ """Rebuild a skill folder from the database at out_dir/<name>. Verifies every file hash."""
50
+ with Neo4jBackend(conn) as backend:
51
+ record = backend.catalog.get(name, revision) # NotFound is a KeyError
52
+ return materialize(record, Path(out_dir) / record.name)
53
+
54
+
55
+ def list_skills(conn: Connection | None = None) -> List[JSON]:
56
+ """Every revision of every name: name, revision, aip_version, published_at, retired, pinned, files, steps."""
57
+ with Neo4jBackend(conn) as backend:
58
+ return backend.catalog.revisions()
aip/errors.py ADDED
@@ -0,0 +1,18 @@
1
+ """The root of every error the SDK raises (`aip.AipError`), in a module of its own so the client's
2
+ HTTP layer and the SDK can both build on it without importing each other."""
3
+
4
+
5
+ class AipError(Exception):
6
+ """An AIP operation that could not be done. `kind` names what went wrong, in the same
7
+ vocabulary as the CLI's error objects and the server's error envelope."""
8
+
9
+ kind = "error"
10
+
11
+ def __init__(self, message: str, kind: str | None = None):
12
+ super().__init__(message)
13
+ self.message = message
14
+ if kind is not None:
15
+ self.kind = kind
16
+
17
+
18
+ __all__ = ["AipError"]
aip/model/__init__.py ADDED
@@ -0,0 +1,24 @@
1
+ """AIP runtime model."""
2
+
3
+ from aip.model.environment import Requires, RequiresUnmet
4
+ from aip.model.procedure import Procedure
5
+ from aip.model.resources import Asset, Reference, Resource, ResourceLoader, Script
6
+ from aip.model.steps import (
7
+ DEFAULT_MIN_CONFIDENCE, DEFAULT_NOUL_MARGIN,
8
+ BaseStep, ClientTask, Decision, DecisionQuestion, EndStep, Execution, Meta, Node,
9
+ Router, State, StepResponse, describe_next,
10
+ )
11
+ from aip.model.types import (
12
+ JSON, DataType, InputValidationError, Inputs, OutputValidationError, ScriptFailed, ScriptTimeout, StepError,
13
+ describe_inputs, project, to_json_schema, validate_input, validate_output,
14
+ )
15
+
16
+ __all__ = [
17
+ "Requires", "RequiresUnmet", "Procedure", "Asset", "Reference", "Resource", "ResourceLoader", "Script",
18
+ "DEFAULT_MIN_CONFIDENCE", "DEFAULT_NOUL_MARGIN",
19
+ "BaseStep", "ClientTask", "Decision", "DecisionQuestion", "EndStep", "Execution", "Meta", "Node",
20
+ "Router", "State", "StepResponse", "describe_next",
21
+ "JSON", "DataType", "InputValidationError", "Inputs", "OutputValidationError", "ScriptFailed", "ScriptTimeout",
22
+ "StepError", "describe_inputs", "project",
23
+ "to_json_schema", "validate_input", "validate_output",
24
+ ]
aip/model/engine.py ADDED
@@ -0,0 +1,314 @@
1
+ """The run loop: one procedure, one cursor, one answer at a time.
2
+
3
+ A run is a `Cursor`: the step whose output the next input answers (`after`), the full state,
4
+ the history, and what the run waits for (`pause`). `start` opens one from the start input;
5
+ `submit` carries one thing to it: the answer to its pause, or nothing to retry a failed step.
6
+ Each steps the procedure until a pause, the end, or a failure, and returns an `Advance`.
7
+
8
+ The same loop runs in both places a run can live: the local client (`aip run ./folder`)
9
+ keeps the cursor in its run file; the server keeps it in its run backend and the client
10
+ holds only the run id. Neither keeps anything in memory between calls.
11
+
12
+ Pause kinds, as `cursor.pause["kind"]`:
13
+
14
+ - `client_task`: the client must answer. The block is what the CLI prints, minus `run_id` and
15
+ `run_file`.
16
+ - `decision`: every decision stops here; the loop never calls a decision model. The client
17
+ resolves it (`aip.client.resolver`) with its own model when one is configured, else prints
18
+ it for the agent to answer; the next `submit` carries the answers and their attribution
19
+ (`Decision.accept_answers`). The block also carries the author's `thresholds` and, when the
20
+ step sets `history: true`, the run's `history`: what a resolver needs, never printed (`PRIVATE`).
21
+ A `review` (the model answered a question under its threshold) is the client's pause, not
22
+ the loop's: the loop still waits at the decision.
23
+ - `execute`: an execution step, in a run whose loop does not run scripts (`scripts=False`: the
24
+ server's, and the local client's, which runs them itself between calls). The block is
25
+ `Execution.request`; the next `submit` carries the client's report of running it (`{"output":
26
+ {...}, "seconds"}` or a failure, see `Execution.accept_report`). Never printed by the CLI.
27
+ - `error`: a step failed; `after`, `state`, and `history` are as they were before it, so a
28
+ `submit` with no answer retries it.
29
+ - `done`: the end was reached; `state` is the end step's inputs.
30
+ """
31
+
32
+ from __future__ import annotations
33
+
34
+ from dataclasses import dataclass, field
35
+ from typing import Any, Dict, List
36
+
37
+ from aip.model.procedure import Procedure
38
+ from aip.model.steps import Decision, Execution, describe_next, threshold
39
+ from aip.model.types import (
40
+ JSON, InputValidationError, OutputValidationError, StepError, project, validate_input, validate_output,
41
+ )
42
+
43
+ # The error kinds of the error object (`docs/cli-json.md`); anything else is reported as `server`.
44
+ ERROR_KINDS = ("script_failed", "invalid_input", "invalid_output", "requires_unmet", "timeout", "server")
45
+
46
+ PAUSED = ("client_task", "decision")
47
+
48
+ # Keys of a pause block that are for the client program, not the agent: the CLI never prints them.
49
+ PRIVATE = ("thresholds", "history", "resolution")
50
+
51
+
52
+ @dataclass
53
+ class Cursor:
54
+ after: str | None = None
55
+ state: JSON = field(default_factory=dict)
56
+ history: List[JSON] = field(default_factory=list)
57
+ pause: JSON | None = None
58
+
59
+ @property
60
+ def status(self) -> str:
61
+ """The run's status: `paused`, `failed`, `done`, or `running` (nothing pending)."""
62
+ kind = (self.pause or {}).get("kind")
63
+ return "paused" if kind in PAUSED else "failed" if kind == "error" else "done" if kind == "done" else "running"
64
+
65
+
66
+ @dataclass
67
+ class Advance:
68
+ """What one `start` or `submit` did.
69
+
70
+ cursor: where the run is now; `None` when nothing is worth keeping (the start input was
71
+ rejected before any step ran)
72
+ entries: the history entries this call added, in order (also at the end of `cursor.history`)
73
+ lines: the `--progress` line of every step this call completed, in order
74
+ error: the error object when the call failed; `kept` says the run did not move (an answer
75
+ that does not fit its pause: answer it again)
76
+ failure: the history entry recording a step that failed while running (the server's ledger)
77
+ exc: the exception behind `error`, for `--debug`
78
+ """
79
+ cursor: Cursor | None
80
+ entries: List[JSON] = field(default_factory=list)
81
+ lines: List[JSON] = field(default_factory=list)
82
+ error: JSON | None = None
83
+ kept: bool = False
84
+ failure: JSON | None = None
85
+ exc: BaseException | None = None
86
+
87
+ @property
88
+ def resumable(self) -> bool:
89
+ """Whether there is a run to come back to: the pause that still stands, or the retry point."""
90
+ return self.kept or self.cursor is not None
91
+
92
+ def outcome(self) -> JSON:
93
+ """The paused, done, or error object, without `run_id` and `run_file` (the caller adds them)."""
94
+ if self.error is not None:
95
+ return dict(self.error)
96
+ pause = self.cursor.pause
97
+ if pause["kind"] == "done":
98
+ return {"done": True, "state": pause["state"]}
99
+ return {"paused": pause["kind"], **{k: v for k, v in pause.items() if k != "kind"}}
100
+
101
+
102
+ # ---------------------------------------------------------------------------- errors
103
+
104
+
105
+ def error_object(exc: BaseException) -> JSON:
106
+ """The error object's kind, step, message and per-kind detail for a step that raised."""
107
+ if isinstance(exc, StepError):
108
+ kind = exc.kind if exc.kind in ERROR_KINDS else "server"
109
+ return {"error": kind, "step": exc.step, "message": str(exc), **exc.fields()}
110
+ return {"error": "server", "step": None, "message": f"{type(exc).__name__}: {exc}"}
111
+
112
+
113
+ def _answer_error(error: JSON) -> bool:
114
+ """An answer to a pause that does not fit, as opposed to a step that failed while running."""
115
+ return error["error"] in ("invalid_input", "invalid_output") and "script" not in error
116
+
117
+
118
+ # ----------------------------------------------------------------------------- lines
119
+
120
+
121
+ def step_line(entry: JSON) -> JSON:
122
+ """The `--progress` line for one completed step, from its history entry."""
123
+ line: JSON = {"event": "step", "step": entry["step"], "kind": entry["kind"]}
124
+ if entry["kind"] == "router":
125
+ line["to"] = entry["result"]["to"]
126
+ elif entry["kind"] == "decision":
127
+ line["resolver"] = (entry.get("attribution") or {}).get("resolver", "manual")
128
+ elif entry["kind"] == "execution" and "seconds" in entry:
129
+ line["seconds"] = entry["seconds"]
130
+ return line
131
+
132
+
133
+ def settled_line(pause: JSON) -> JSON | None:
134
+ """The line for a paused step, printed once its answer is accepted."""
135
+ if pause["kind"] == "client_task":
136
+ return {"event": "step", "step": pause["step"], "kind": "client_task"}
137
+ return None
138
+
139
+
140
+ # ---------------------------------------------------------------------------- pauses
141
+
142
+
143
+ def pause_of(response: JSON) -> JSON | None:
144
+ """The pause a step response asks for: a client task. Its `state` is the step's projected input."""
145
+ if response["next"] is None or response["kind"] != "client_task":
146
+ return None
147
+ entry, result = response["history"][-1], response["result"]
148
+ return {"kind": "client_task", "step": response["ran"], "task": result["task"], "state": entry["input"],
149
+ "references": result["references"], "answer_with": result["expects"]}
150
+
151
+
152
+ def thresholds_of(step: Decision) -> Dict[str, float]:
153
+ """Every question's threshold as the author set it in SKILL.md, the type's default otherwise."""
154
+ return {name: threshold(q.type, step.thresholds, name) for name, q in step.questions.items()}
155
+
156
+
157
+ def decision_pause(step: Decision, state: JSON, history: List[JSON]) -> JSON:
158
+ """The pause at a decision: what the decision model is given (`questions`, `state`, and `history`
159
+ when the step asks for it), and the thresholds the client's resolver applies."""
160
+ pause = {"kind": "decision", "step": step.name, "questions": describe_next(step)["questions"],
161
+ "state": project(state, step.inputs), "thresholds": thresholds_of(step)}
162
+ if step.history:
163
+ pause["history"] = history
164
+ return pause
165
+
166
+
167
+ # ------------------------------------------------------------------------------ loop
168
+
169
+
170
+ def start(procedure: Procedure, payload: JSON, scripts: bool = True) -> Advance:
171
+ """Open a run on the start input and step it until it must stop. With `scripts` false the run
172
+ stops at each execution step (`execute`) instead of running its script here."""
173
+ return _drive(procedure, scripts, None, payload, [])
174
+
175
+
176
+ def submit(procedure: Procedure, cursor: Cursor, answer: JSON | None, scripts: bool = True,
177
+ attribution: JSON | None = None) -> Advance:
178
+ """Carry one thing to a run: the answer to its pause (at a decision, with the `attribution` of
179
+ whoever resolved it; None is a manual answer), the report of a script the client ran, or
180
+ (`None`, at a failed step) a retry. A retry may carry keys too; they are merged over the
181
+ state before the step. An answer that does not fit leaves the run where it was (`kept`)."""
182
+ pause = cursor.pause or {}
183
+ kind = pause.get("kind")
184
+ if kind == "done":
185
+ return Advance(cursor, kept=True, error={
186
+ "error": "server", "step": None, "message": "the run is done; there is nothing to answer"})
187
+ if kind == "error":
188
+ return _drive(procedure, scripts, cursor.after, {**cursor.state, **(answer or {})}, cursor.history)
189
+ if kind == "execute":
190
+ if not _is_report(answer):
191
+ return Advance(cursor, kept=True, error={
192
+ "error": "invalid_output", "step": pause["step"],
193
+ "message": f"step {pause['step']!r} runs on the client: post the report of running its script, "
194
+ '{"output": {...}} or {"error": "script_failed"|"timeout"|"requires_unmet", ...}',
195
+ "missing": ["output"], "invalid": []})
196
+ return _drive(procedure, scripts, cursor.after, cursor.state, cursor.history, report=answer)
197
+ if kind not in PAUSED:
198
+ return Advance(cursor, kept=True, error={
199
+ "error": "server", "step": None, "message": f"the run is not paused (status {cursor.status})"})
200
+ if answer is None:
201
+ keys = list(pause["questions"] if kind == "decision" else pause.get("answer_with", {}))
202
+ return Advance(cursor, kept=True, error={
203
+ "error": "invalid_output", "step": pause["step"],
204
+ "message": f"resume needs an answer for the paused {kind} step {pause['step']!r} (--input <answer.json>)",
205
+ "missing": keys, "invalid": []})
206
+ if kind == "decision":
207
+ return _drive(procedure, scripts, cursor.after, cursor.state, cursor.history,
208
+ answering=pause, answers=(answer, attribution))
209
+ try:
210
+ validate_output(pause["step"], pause["answer_with"], answer, strict=False)
211
+ except OutputValidationError as exc:
212
+ return Advance(cursor, kept=True, error=error_object(exc), exc=exc)
213
+ # the client task's entry is written now, like a decision's: the task it was given and the answer
214
+ outputs = {k: answer[k] for k in pause["answer_with"]}
215
+ entry = {"step": pause["step"], "kind": "client_task", "input": pause["state"],
216
+ "result": {"task": pause["task"], "references": pause["references"], "answer": outputs}}
217
+ return _drive(procedure, scripts, cursor.after, {**cursor.state, **outputs}, cursor.history,
218
+ answering=pause, answered=entry)
219
+
220
+
221
+ def _is_report(answer: JSON | None) -> bool:
222
+ """A client's report of running a script: its output, or a failure of a known kind."""
223
+ if not isinstance(answer, dict):
224
+ return False
225
+ if "error" in answer:
226
+ return answer["error"] in ("script_failed", "timeout", "requires_unmet")
227
+ return isinstance(answer.get("output"), dict)
228
+
229
+
230
+ def _drive(procedure: Procedure, scripts: bool, after: str | None, payload: JSON,
231
+ history: List[JSON], answering: JSON | None = None, answers: tuple[JSON, JSON | None] | None = None,
232
+ report: JSON | None = None, answered: JSON | None = None) -> Advance:
233
+ """Step until a pause, the end, or a failure. `answering` is the pause this call answers: a bad
234
+ answer leaves it in place. `answers` (the answers and their attribution) answers a decision
235
+ first, `report` an execution step the client ran, and `answered` is the history entry of the
236
+ client task this call answers."""
237
+ carried = len(history)
238
+ if answered is not None:
239
+ history = [*history, answered]
240
+ lines: List[JSON] = []
241
+
242
+ def settle() -> None:
243
+ nonlocal answering
244
+ line = settled_line(answering) if answering is not None else None
245
+ if line is not None:
246
+ lines.append(line)
247
+ answering = None
248
+
249
+ def stop(pause: JSON) -> Advance:
250
+ return Advance(Cursor(after, payload, history, pause), entries=history[carried:], lines=lines)
251
+
252
+ while True:
253
+ node = None
254
+ try:
255
+ node, routed = procedure.resolve(after, payload)
256
+ if answers is not None:
257
+ if not isinstance(node, Decision):
258
+ raise KeyError(f"the step after {after!r} is not a decision")
259
+ response = node.accept_answers(payload, [*history, *routed], *answers).to_dict()
260
+ answers = None
261
+ elif report is not None:
262
+ if not isinstance(node, Execution):
263
+ raise KeyError(f"the step after {after!r} is not an execution step")
264
+ response = node.accept_report(payload, [*history, *routed], report).to_dict()
265
+ report = None
266
+ elif isinstance(node, Decision):
267
+ validate_input(node.name, node.inputs, payload) # before asking anyone
268
+ settle()
269
+ return stop(decision_pause(node, payload, [*history, *routed]))
270
+ elif isinstance(node, Execution) and not scripts:
271
+ request = node.request(payload)
272
+ settle()
273
+ return stop(request)
274
+ else:
275
+ response = procedure.run(after, payload, history).to_dict()
276
+ except Exception as exc:
277
+ return _failed(exc, node, after, payload, history, carried, lines, keep=answering is not None)
278
+ settle()
279
+ pause = pause_of(response)
280
+ if pause is not None: # its entry is written when it is answered
281
+ response["history"] = response["history"][:-1]
282
+ for entry in response["history"][len(history):]:
283
+ if entry["kind"] != "end":
284
+ lines.append(step_line(entry))
285
+ after, payload, history = response["ran"], response["suggested"], response["history"]
286
+ if response["next"] is None:
287
+ payload = response["result"]
288
+ return stop({"kind": "done", "state": response["result"]})
289
+ if pause is not None:
290
+ return stop(pause)
291
+
292
+
293
+ def _failed(exc: BaseException, node: Any, after: str | None, state: JSON, history: List[JSON], carried: int,
294
+ lines: List[JSON], keep: bool) -> Advance:
295
+ """A step failed. The run waits at the state before it, to be retried, unless the failure is a
296
+ bad answer to a pause (`keep`: the pause stands, answer it again) or the start input was
297
+ rejected before any step ran (start again)."""
298
+ error = error_object(exc)
299
+ if keep and _answer_error(error):
300
+ return Advance(None, error=error, kept=True, exc=exc)
301
+ if after is None and not history and isinstance(exc, InputValidationError):
302
+ return Advance(None, error=error, exc=exc)
303
+ detail = exc.fields() if isinstance(exc, StepError) else {}
304
+ if isinstance(getattr(exc, "host", None), str):
305
+ detail["host"] = exc.host # the machine that reported a script's failure
306
+ failure = {"step": getattr(node, "name", error["step"]), "kind": "error", "step_kind": getattr(node, "kind", None),
307
+ "input": state, "result": {"error": f"{type(exc).__name__}: {exc}", **detail}}
308
+ pause = {"kind": "error", "step": error["step"], "error": error["error"]}
309
+ return Advance(Cursor(after, state, history, pause), entries=history[carried:], lines=lines,
310
+ error=error, failure=failure, exc=exc)
311
+
312
+
313
+ __all__ = ["Advance", "Cursor", "ERROR_KINDS", "PAUSED", "PRIVATE", "decision_pause", "error_object", "pause_of",
314
+ "settled_line", "start", "step_line", "submit", "thresholds_of"]