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/model/steps.py ADDED
@@ -0,0 +1,607 @@
1
+ """Step model: state, meta, nodes, and the accept flow."""
2
+
3
+ from abc import ABC, abstractmethod
4
+ from dataclasses import dataclass, field
5
+ from pathlib import Path
6
+ from typing import Any, ClassVar, Dict, List, TypeAlias
7
+ import copy
8
+ import json
9
+ import os
10
+ import subprocess
11
+ import sys
12
+ import time
13
+
14
+ from typesafe_sdk import Choice, Noul, Score, SystemOneResponse, TypeSafeClient
15
+
16
+ from aip.model.environment import PYTHON, Requires, RequiresUnmet
17
+ from aip.model.resources import Asset, Reference, ResourceLoader, Script
18
+ from aip.model.types import (
19
+ JSON, DataType, InputValidationError, Inputs, OutputValidationError, ScriptFailed, ScriptTimeout,
20
+ describe_inputs, project, validate_input, validate_output,
21
+ )
22
+
23
+ DecisionQuestion: TypeAlias = Noul | Choice | Score
24
+
25
+ # Default decision thresholds. Noul: flag when |p - 0.5| < margin.
26
+ # Choice / Score: flag when the model's confidence < min_confidence.
27
+ DEFAULT_NOUL_MARGIN = 0.15
28
+ DEFAULT_MIN_CONFIDENCE = 0.6
29
+
30
+ @dataclass
31
+ class State:
32
+ """
33
+ What one step sees: the state projected to the step's declared `inputs`, plus the
34
+ history the client carried in. Built by `accept()`, never persisted server-side.
35
+ """
36
+ currentState: JSON = field(default_factory=dict)
37
+ history: List[JSON] = field(default_factory=list)
38
+
39
+
40
+ @dataclass
41
+ class Meta:
42
+ """Package metadata, owned by the Procedure."""
43
+ name: str
44
+ description: str = ""
45
+ version: str = "0.1.0"
46
+
47
+
48
+ @dataclass
49
+ class StepResponse:
50
+ """
51
+ What the server returns after running a step.
52
+
53
+ ran: name of the step that ran
54
+ kind: "decision" | "client_task" | "execution" | "end"
55
+ result: raw output of the step
56
+ suggested: the full state after this step: the posted state plus the keys this step
57
+ produced. The client posts it as the next input (answers merged over it)
58
+ review: items the client should look at before accepting `suggested`
59
+ (e.g. low-confidence decision answers); empty means safe to pass through
60
+ next: description of what comes next (see `describe_next`); None at the end
61
+ history: the carried-in history plus this step's entry
62
+ """
63
+ ran: str
64
+ kind: str
65
+ result: JSON
66
+ suggested: JSON
67
+ review: List[JSON]
68
+ next: JSON | None
69
+ history: List[JSON]
70
+
71
+ def to_dict(self) -> JSON:
72
+ return {
73
+ "ran": self.ran, "kind": self.kind, "result": self.result, "suggested": self.suggested,
74
+ "review": self.review, "next": self.next, "history": self.history,
75
+ }
76
+
77
+
78
+ @dataclass(kw_only=True)
79
+ class EndStep:
80
+ """Terminal node. `inputs` is the shape of the final state the client receives."""
81
+ kind: ClassVar[str] = "end"
82
+ name: str = "end"
83
+ inputs: Inputs = field(default_factory=dict)
84
+
85
+
86
+ def branch_key(value: Any) -> str:
87
+ """Branch keys are YAML strings; collapsed answers are typed. `true`/`false` for a
88
+ noul, the label for a choice, the level number for a score."""
89
+ if isinstance(value, bool):
90
+ return "true" if value else "false"
91
+ return str(value)
92
+
93
+
94
+ @dataclass(kw_only=True)
95
+ class Router:
96
+ """
97
+ Dumb router: maps the value the client posted under `branch_on` to the next node.
98
+ Calls no model, has no endpoint. The server walks routers internally after the
99
+ client's input arrives; the client only sees the branches for schema purposes.
100
+
101
+ branch_on: key in the posted input whose value selects the branch
102
+ branches: branch value -> node; needs two or more
103
+ """
104
+ kind: ClassVar[str] = "router"
105
+ name: str
106
+ branch_on: str
107
+ branches: Dict[str, "Node"]
108
+
109
+ def route(self, payload: JSON) -> "Node":
110
+ if self.branch_on not in payload:
111
+ raise InputValidationError(self.name, [f"missing routing key {self.branch_on!r}"], missing=[self.branch_on])
112
+ value = payload[self.branch_on]
113
+ key = branch_key(value)
114
+ if key not in self.branches:
115
+ raise InputValidationError(
116
+ self.name, [f"{self.branch_on}={value!r} has no branch; options: {list(self.branches)}"],
117
+ invalid=[self.branch_on])
118
+ return self.branches[key]
119
+
120
+
121
+ @dataclass(kw_only=True)
122
+ class BaseStep(ABC):
123
+ """
124
+ A node the server runs. Steps are configuration; run state flows through `accept`.
125
+
126
+ name: unique within the procedure; endpoints and history refer to it
127
+ inputs: the keys this step reads; validated on accept, and the only keys it sees
128
+ outputs: the keys this step adds to the state; its result is validated against them
129
+ inputsTo: the node that receives this step's output (a step, a router, or the end)
130
+ """
131
+ kind: ClassVar[str] = "step"
132
+ name: str
133
+ inputs: Inputs = field(default_factory=dict)
134
+ outputs: Inputs = field(default_factory=dict)
135
+ inputsTo: "Node | None" = None
136
+ loader: ResourceLoader | None = None
137
+ meta: Meta | None = None
138
+
139
+ @abstractmethod
140
+ def _invoke(self, state: State) -> JSON:
141
+ """Run the step against the accepted state and return its raw result."""
142
+
143
+ def output_types(self) -> Inputs:
144
+ """The keys this step adds to the state, with their types."""
145
+ return dict(self.outputs)
146
+
147
+ def produced(self, result: JSON) -> JSON:
148
+ """The keys this step's result adds to the state. By default the (validated) result itself."""
149
+ return dict(result)
150
+
151
+ def review(self, result: JSON) -> List[JSON]:
152
+ """Items the client should look at before passing `suggested` through."""
153
+ return []
154
+
155
+ def accept(self, payload: JSON, history: List[JSON]) -> StepResponse:
156
+ """
157
+ Validate the posted state against the declared inputs, run the step on just those
158
+ keys, and merge what it produced back into the full state.
159
+ """
160
+ validate_input(self.name, self.inputs, payload)
161
+ state = State(currentState=project(payload, self.inputs), history=copy.deepcopy(history))
162
+ began = time.monotonic()
163
+ result = self._invoke(state)
164
+ entry = {"step": self.name, "kind": self.kind, "input": state.currentState, "result": result}
165
+ if isinstance(self, Execution):
166
+ entry["seconds"] = round(time.monotonic() - began, 3)
167
+ return StepResponse(
168
+ ran=self.name,
169
+ kind=self.kind,
170
+ result=result,
171
+ suggested={**payload, **self.produced(result)},
172
+ review=self.review(result),
173
+ next=describe_next(self.inputsTo),
174
+ history=[*history, entry],
175
+ )
176
+
177
+ def _require_loader(self) -> ResourceLoader:
178
+ if self.loader is None:
179
+ raise RuntimeError(f"{type(self).__name__} {self.name!r} needs a ResourceLoader to resolve resources")
180
+ return self.loader
181
+
182
+
183
+ Node: TypeAlias = BaseStep | Router | EndStep
184
+
185
+
186
+ def describe_next(node: Node | None) -> JSON | None:
187
+ """
188
+ Client-facing description of the node that receives the next input. Routers are
189
+ expanded into their branches so the client can see every possible input shape,
190
+ but the client never resolves them; the server does on the next call.
191
+ """
192
+ if node is None:
193
+ return None
194
+ if isinstance(node, Router):
195
+ return {
196
+ "step": node.name, "kind": node.kind, "branch_on": node.branch_on,
197
+ "branches": {value: describe_next(target) for value, target in node.branches.items()},
198
+ }
199
+ described: JSON = {"step": node.name, "kind": node.kind, "inputs": describe_inputs(node.inputs)}
200
+ if isinstance(node, Decision):
201
+ described["questions"] = {name: q.model_dump(exclude_none=True) for name, q in node.questions.items()}
202
+ return described
203
+
204
+
205
+ @dataclass(kw_only=True)
206
+ class Decision(BaseStep):
207
+ """
208
+ Runs a SystemOne (TypeSafe / Jev) decision and hands the typed result to the client.
209
+
210
+ The declared inputs are the content being evaluated; the criteria live in each
211
+ question's `instructions`, written by the author. No assets and no framing are injected.
212
+
213
+ questions: keyed by name; answers come back under the same names and, after
214
+ collapse, become state keys of the same name: a decision's outputs
215
+ history: send the run history to the decision model too; off unless the author asks
216
+ thresholds: per-question, the author's, and the only ones applied. Noul: margin around 0.5.
217
+ Choice / Score: minimum confidence. Unset questions use the type's default.
218
+ client: optional injected TypeSafe client (tests, connection reuse); otherwise one
219
+ is opened per invoke using TYPESAFE_API_KEY from the environment
220
+ """
221
+ kind: ClassVar[str] = "decision"
222
+ questions: Dict[str, DecisionQuestion] = field(default_factory=dict)
223
+ thresholds: Dict[str, float] = field(default_factory=dict)
224
+ history: bool = False
225
+ client: TypeSafeClient | None = None
226
+
227
+ ANSWER_TYPES: ClassVar[Dict[str, DataType]] = {
228
+ "noul": DataType.BOOLEAN, "choice": DataType.STRING, "score": DataType.INTEGER}
229
+
230
+ def render(self, state: State) -> JSON:
231
+ """Pure projection of state into the JSON `state` sent to Jev: the declared inputs,
232
+ and the history only when the step asks for it."""
233
+ payload: JSON = {"state": state.currentState}
234
+ if self.history and state.history:
235
+ payload["history"] = state.history
236
+ return payload
237
+
238
+ def output_types(self) -> Inputs:
239
+ """One key per question, typed by what its answer collapses to."""
240
+ return {name: self.ANSWER_TYPES[q.type] for name, q in self.questions.items()}
241
+
242
+ def _invoke(self, state: State) -> JSON:
243
+ """
244
+ Returns the TypeSafe result as a JSON dict:
245
+ {"model": str,
246
+ "usage": {"input_tokens", "output_tokens"},
247
+ "answers": {name: {"type": "noul"|"choice"|"score", ...}}}
248
+ """
249
+ if not self.questions:
250
+ raise ValueError(f"Decision {self.name!r} has no questions to ask")
251
+ payload = self.render(state)
252
+ if self.client is not None:
253
+ result: SystemOneResponse = self.client.system_one(state=payload, questions=self.questions)
254
+ else:
255
+ with TypeSafeClient() as client:
256
+ result = client.system_one(state=payload, questions=self.questions)
257
+ return result.model_dump(mode="json")
258
+
259
+ def accept_answers(self, payload: JSON, history: List[JSON], answers: JSON,
260
+ attribution: JSON | None = None) -> StepResponse:
261
+ """
262
+ The client resolved the decision: `answers` holds one collapsed value per question (bool
263
+ for noul, label for choice, int level for score), and `attribution` says how it got them,
264
+ `{"resolver": "typesafe"|"manual", "model", "confidence": {question: float}|None,
265
+ "reviewed"}`, plus `proposed` (the model's answers before review) when reviewed. None is
266
+ a manual answer. Both are checked and recorded in the history entry.
267
+ """
268
+ validate_input(self.name, self.inputs, payload)
269
+ missing = [q for q in self.questions if q not in answers]
270
+ if missing:
271
+ raise OutputValidationError(self.name, [f"missing answers for {missing}"], missing=missing)
272
+ self.check_answers(answers)
273
+ attribution = manual() if attribution is None else self.check_attribution(attribution)
274
+ result = {"answers": {name: answers[name] for name in self.questions}}
275
+ entry = {"step": self.name, "kind": self.kind, "input": project(payload, self.inputs),
276
+ "result": result, "attribution": attribution}
277
+ return StepResponse(
278
+ ran=self.name, kind=self.kind, result=result,
279
+ suggested={**payload, **result["answers"]},
280
+ review=[], next=describe_next(self.inputsTo), history=[*history, entry],
281
+ )
282
+
283
+ def check_attribution(self, attribution: JSON) -> JSON:
284
+ """The attribution as recorded: a known resolver, a model name, a confidence in 0..1 for
285
+ questions of this step, whether the answers were reviewed, and what was proposed before."""
286
+ errors: List[str] = []
287
+ if not isinstance(attribution, dict):
288
+ raise OutputValidationError(self.name, ["attribution must be an object"], invalid=["attribution"])
289
+ resolver = attribution.get("resolver")
290
+ if resolver not in RESOLVERS:
291
+ errors.append(f"attribution.resolver must be one of {list(RESOLVERS)}, got {resolver!r}")
292
+ model = attribution.get("model")
293
+ if model is not None and not isinstance(model, str):
294
+ errors.append("attribution.model must be a string or null")
295
+ scores = attribution.get("confidence")
296
+ if scores is not None and not (isinstance(scores, dict) and all(
297
+ k in self.questions and isinstance(v, (int, float)) and not isinstance(v, bool) and 0 <= v <= 1
298
+ for k, v in scores.items())):
299
+ errors.append("attribution.confidence must map this step's questions to numbers in 0..1")
300
+ reviewed = attribution.get("reviewed", False)
301
+ if not isinstance(reviewed, bool):
302
+ errors.append("attribution.reviewed must be true or false")
303
+ proposed = attribution.get("proposed")
304
+ if proposed is not None:
305
+ if not isinstance(proposed, dict) or set(proposed) != set(self.questions):
306
+ errors.append("attribution.proposed must answer every question of this step")
307
+ else:
308
+ try:
309
+ self.check_answers(proposed)
310
+ except OutputValidationError as exc:
311
+ errors += [f"attribution.proposed: {e}" for e in exc.errors]
312
+ if resolver == "manual" and (model is not None or scores is not None or proposed is not None):
313
+ errors.append("a manual answer has no model, confidence, or proposed answers")
314
+ if errors:
315
+ raise OutputValidationError(self.name, errors, invalid=["attribution"])
316
+ out = {"resolver": resolver, "model": model, "confidence": scores, "reviewed": reviewed}
317
+ if proposed is not None:
318
+ out["proposed"] = proposed
319
+ return out
320
+
321
+ def check_answers(self, answers: JSON) -> None:
322
+ """Collapsed answers must name only this step's questions and fit each question's type."""
323
+ validate_output(self.name, self.output_types(), {k: v for k, v in answers.items() if k in self.questions},
324
+ strict=False)
325
+ invalid = [key for key in answers if key not in self.questions]
326
+ errors = [f"undeclared output {key!r} (not a question of this step)" for key in invalid]
327
+ for name, q in self.questions.items():
328
+ value = answers[name]
329
+ if q.type == "choice" and value not in q.criteria:
330
+ errors.append(f"{name}: {value!r} is not one of {list(q.criteria)}")
331
+ invalid.append(name)
332
+ if q.type == "score" and isinstance(value, int) and not 0 <= value < len(q.criteria):
333
+ errors.append(f"{name}: level {value} is outside 0..{len(q.criteria) - 1}")
334
+ invalid.append(name)
335
+ if errors:
336
+ raise OutputValidationError(self.name, errors, invalid=invalid)
337
+
338
+ @staticmethod
339
+ def collapse(answer: JSON) -> Any:
340
+ """Discrete value for one answer: noul -> bool, choice -> label, score -> argmax level."""
341
+ match answer["type"]:
342
+ case "noul":
343
+ return answer["noul"] >= 0.5
344
+ case "choice":
345
+ return answer["choice"]
346
+ case "score":
347
+ return int(max(answer["probabilities"], key=answer["probabilities"].get))
348
+ raise ValueError(f"unknown answer type {answer['type']!r}")
349
+
350
+ def produced(self, result: JSON) -> JSON:
351
+ """Each answer collapsed to a discrete value under its question name."""
352
+ missing = [name for name in self.questions if name not in result["answers"]]
353
+ if missing:
354
+ raise OutputValidationError(self.name, [f"no answer for {missing}"])
355
+ return {name: self.collapse(result["answers"][name]) for name in self.questions}
356
+
357
+ def review(self, result: JSON) -> List[JSON]:
358
+ """Answers whose uncertainty crosses the threshold, with what the client needs to decide."""
359
+ return flag(result["answers"], self.thresholds)
360
+
361
+
362
+ def threshold(question_type: str, thresholds: Dict[str, float], name: str) -> float:
363
+ """A question's threshold: the author's, else its type's default."""
364
+ return thresholds.get(name, DEFAULT_NOUL_MARGIN if question_type == "noul" else DEFAULT_MIN_CONFIDENCE)
365
+
366
+
367
+ def flag(answers: JSON, thresholds: Dict[str, float]) -> List[JSON]:
368
+ """The model's answers (`{name: {"type", ...}}`) whose uncertainty crosses their threshold: a noul
369
+ within its margin of 0.5, a choice or score under its minimum confidence."""
370
+ flagged: List[JSON] = []
371
+ for name, answer in answers.items():
372
+ limit = threshold(answer["type"], thresholds, name)
373
+ if answer["type"] == "noul":
374
+ if abs(answer["noul"] - 0.5) < limit:
375
+ flagged.append({"question": name, "type": "noul", "noul": answer["noul"],
376
+ "reason": f"within {limit} of 0.5"})
377
+ elif answer["confidence"] < limit:
378
+ flagged.append({"question": name, "type": answer["type"], "confidence": answer["confidence"],
379
+ "probabilities": answer["probabilities"], "reason": f"confidence below {limit}"})
380
+ return flagged
381
+
382
+
383
+ def confidence(answer: JSON) -> float:
384
+ """How sure the model is of its collapsed answer: a noul's probability of the side it chose, a
385
+ choice's or score's own confidence."""
386
+ if answer["type"] == "noul":
387
+ return round(max(answer["noul"], 1 - answer["noul"]), 4)
388
+ return answer["confidence"]
389
+
390
+
391
+ RESOLVERS = ("typesafe", "manual")
392
+
393
+
394
+ def manual() -> JSON:
395
+ """The attribution of a decision answered with no model: by the client, or the agent at a pause."""
396
+ return {"resolver": "manual", "model": None, "confidence": None, "reviewed": False}
397
+
398
+
399
+ class _SafeMap(dict):
400
+ """format_map helper: unknown placeholders are left intact instead of raising."""
401
+ def __missing__(self, key: str) -> str:
402
+ return "{" + key + "}"
403
+
404
+
405
+ @dataclass(kw_only=True)
406
+ class ClientTask(BaseStep):
407
+ """
408
+ A step the client performs itself (text generation, synthesis, reasoning). Fallback
409
+ for anything not expressible as a Decision or Execution.
410
+
411
+ The template is the whole task: prose rendered at invoke time with `{key}`
412
+ placeholders drawn from the step's declared inputs, plus `{assets[name]}` and
413
+ `{meta.name}`. Nothing is prepended to it. The client does the task and answers with
414
+ the step's `outputs`.
415
+
416
+ template: the asset holding the task template
417
+ assets: extra eager resources available to the template as {assets[name]}
418
+ references: lazy resources; only uri + description are handed to the client
419
+ """
420
+ kind: ClassVar[str] = "client_task"
421
+ template: Asset
422
+ assets: List[Asset] = field(default_factory=list)
423
+ references: List[Reference] = field(default_factory=list)
424
+
425
+ def render(self, state: State) -> str:
426
+ """Pure projection of the template over state, assets, and meta."""
427
+ loader = self._require_loader()
428
+ mapping = _SafeMap(state.currentState)
429
+ mapping["assets"] = loader.load_all(self.assets)
430
+ mapping["meta"] = self.meta
431
+ return loader.load(self.template).format_map(mapping)
432
+
433
+ def _invoke(self, state: State) -> JSON:
434
+ """Hands the rendered task, the reference index, and the keys to answer with to the client."""
435
+ return {"task": self.render(state), "references": [r.summary() for r in self.references],
436
+ "expects": describe_inputs(self.outputs)}
437
+
438
+ def produced(self, result: JSON) -> JSON:
439
+ """Nothing yet: the client's answer adds the outputs, checked when it is posted."""
440
+ return {}
441
+
442
+
443
+ WORKDIR = "AIP_WORKDIR"
444
+
445
+
446
+ def run_script(step: str, script: str, argv: List[str], stdin: JSON, cwd: Path, timeout: float | None,
447
+ workdir: Path | None = None) -> JSON:
448
+ """Run one script under the stdin/stdout contract and return the JSON object it printed.
449
+
450
+ The script runs from `cwd` (its own folder) with `AIP_WORKDIR` set to `workdir`, the run's
451
+ working directory, where it reads and writes the run's files. Raises `ScriptTimeout`, or
452
+ `ScriptFailed` for a non-zero exit or stdout that is not one JSON object. The result is not
453
+ checked against the step's outputs here; `Execution.check` does that.
454
+ """
455
+ env = {**os.environ, WORKDIR: str(Path(workdir or Path.cwd()).resolve())}
456
+ try:
457
+ proc = subprocess.run(argv, input=json.dumps(stdin), capture_output=True, text=True, cwd=cwd,
458
+ timeout=timeout, env=env)
459
+ except subprocess.TimeoutExpired as err:
460
+ raise ScriptTimeout(step, script, timeout) from err
461
+ stderr = proc.stderr.strip()
462
+ if proc.returncode != 0:
463
+ raise ScriptFailed(step, script, proc.returncode, stderr, failed_message(script, proc.returncode, stderr))
464
+
465
+ out = proc.stdout.strip()
466
+ if not out:
467
+ return {}
468
+ try:
469
+ result = json.loads(out)
470
+ except json.JSONDecodeError as err:
471
+ raise ScriptFailed(step, script, 0, stderr,
472
+ f"Script {script} did not write JSON to stdout: {err}\n{out[:500]}") from err
473
+ if not isinstance(result, dict):
474
+ raise ScriptFailed(step, script, 0, stderr,
475
+ f"Script {script} must write a JSON object, got {type(result).__name__}")
476
+ return result
477
+
478
+
479
+ def failed_message(script: str, exit_code: int, stderr: str) -> str:
480
+ return f"Script {script} exited with {exit_code}:\n{stderr}"
481
+
482
+
483
+ def launch(command: List[str] | None, path: Path, python: Path | str | None = None) -> List[str]:
484
+ """The argument list for a script at `path`: `command`, or `python` on the script. A leading
485
+ `python` is `python` (default: this process's own interpreter)."""
486
+ python = str(python or sys.executable)
487
+ if command is None:
488
+ return [python, str(path)]
489
+ return [python if arg == PYTHON and i == 0 else arg for i, arg in enumerate(command)]
490
+
491
+
492
+ @dataclass(kw_only=True)
493
+ class Execution(BaseStep):
494
+ """
495
+ Executes an action rather than making a decision. Analogous to a tool call. For now
496
+ a script in the package; MCP and endpoints can be added later.
497
+
498
+ Script contract:
499
+ stdin one JSON object: {"state": <the declared inputs only>, "assets": {name: content},
500
+ "expects": <describe_next of the node after this one>}
501
+ (`currentState` carries the same object for one version, for older scripts)
502
+ stdout one JSON object holding exactly the declared `outputs` (empty stdout is {});
503
+ a missing, mistyped, or undeclared key fails the step
504
+ stderr diagnostics; carried in the `script_failed` error when the exit code is non-zero
505
+ env `AIP_WORKDIR`: the run's working directory, where the run's files are
506
+ The script runs from its folder with `command` when the step declares one, otherwise
507
+ `python <script>`. Before it runs, the skill's `requires` block is checked against the
508
+ machine that runs it (`requires_unmet` names what is missing).
509
+
510
+ The script runs on the client. A run that cannot run it in this process (the server's)
511
+ stops at the step with `request()`, what the client needs to run it, and continues with
512
+ `accept_report()` when the client posts what happened. `_invoke` runs it in-process.
513
+
514
+ script: the Script resource to run
515
+ command: the argument list that launches the script, from its folder; None is `python <script>`
516
+ requires: the skill's environment declaration, shared by every Execution of the procedure
517
+ assets: constant inputs the script always receives, e.g. a JSON config. Re-read from
518
+ disk on every invoke so edits are picked up.
519
+ timeout: seconds before the script is killed; None waits forever
520
+ python: the interpreter for a `python` launcher in-process; None is this process's own
521
+ """
522
+ kind: ClassVar[str] = "execution"
523
+ script: Script
524
+ assets: List[Asset] = field(default_factory=list)
525
+ timeout: float | None = 60.0
526
+ command: List[str] | None = None
527
+ requires: Requires | None = None
528
+ python: Path | None = None
529
+
530
+ @property
531
+ def script_path(self) -> str:
532
+ """The script as the SKILL.md names it, relative to the skill root: `scripts/x.py`."""
533
+ return Path(*self.script.uri.parts[1:]).as_posix()
534
+
535
+ def render(self, state: State) -> JSON:
536
+ """Pure projection of the declared inputs + assets into the script's stdin payload."""
537
+ payload: JSON = {"state": state.currentState, "currentState": state.currentState}
538
+ if self.assets:
539
+ payload["assets"] = self._require_loader().load_all(self.assets, fresh=True)
540
+ payload["expects"] = describe_next(self.inputsTo)
541
+ return payload
542
+
543
+ def argv(self, path: Path) -> List[str]:
544
+ """The launch command: the step's `command`, or `python` on the script."""
545
+ return launch(self.command, path, self.python)
546
+
547
+ def request(self, payload: JSON) -> JSON:
548
+ """What a client needs to run this step itself on `payload` (the full state, checked against
549
+ the declared inputs): the script, its launch command, the rendered stdin, the timeout,
550
+ and the skill's `requires`. The stop the server's run waits at (kind `execute`)."""
551
+ validate_input(self.name, self.inputs, payload)
552
+ r = self.requires
553
+ return {"kind": "execute", "step": self.name, "script": self.script_path, "command": self.command,
554
+ "stdin": self.render(State(currentState=project(payload, self.inputs))), "timeout": self.timeout,
555
+ "requires": None if r is None else {"interpreter": r.interpreter, "version": r.version,
556
+ "packages": list(r.packages), "tools": list(r.tools)}}
557
+
558
+ def check(self, result: JSON) -> JSON:
559
+ """The script's result, checked against the declared outputs."""
560
+ try:
561
+ validate_output(self.name, self.outputs, result)
562
+ except OutputValidationError as err:
563
+ err.script = self.script_path
564
+ raise
565
+ return result
566
+
567
+ def accept_report(self, payload: JSON, history: List[JSON], report: JSON) -> StepResponse:
568
+ """Continue after the client ran the script: `report` is `{"output": {...}, "seconds"}`, or
569
+ a failure `{"error": "script_failed"|"timeout"|"requires_unmet", ...}` with its detail
570
+ (exit code and stderr, the timeout, the missing items), raised here as that error so the
571
+ run records it like a failure in-process."""
572
+ validate_input(self.name, self.inputs, payload)
573
+ if "error" in report:
574
+ raise self.reported_error(report)
575
+ result = self.check(report["output"])
576
+ entry = {"step": self.name, "kind": self.kind, "input": project(payload, self.inputs), "result": result}
577
+ if isinstance(report.get("seconds"), (int, float)):
578
+ entry["seconds"] = round(float(report["seconds"]), 3)
579
+ if isinstance(report.get("host"), str):
580
+ entry["host"] = report["host"]
581
+ return StepResponse(ran=self.name, kind=self.kind, result=result, suggested={**payload, **result},
582
+ review=[], next=describe_next(self.inputsTo), history=[*history, entry])
583
+
584
+ def reported_error(self, report: JSON) -> Exception:
585
+ """The error a client's failure report stands for; `host` is the machine that reported it."""
586
+ kind, script = report["error"], self.script_path
587
+ if kind == "timeout":
588
+ exc: Exception = ScriptTimeout(self.name, script, report.get("seconds", self.timeout))
589
+ elif kind == "requires_unmet":
590
+ exc = RequiresUnmet(self.name, [str(m) for m in report.get("missing") or []])
591
+ else:
592
+ exit_code, stderr = int(report.get("exit_code", 0) or 0), str(report.get("stderr", ""))
593
+ exc = ScriptFailed(self.name, script, exit_code, stderr,
594
+ report.get("message") or failed_message(script, exit_code, stderr))
595
+ if isinstance(report.get("host"), str):
596
+ exc.host = report["host"]
597
+ return exc
598
+
599
+ def _invoke(self, state: State) -> JSON:
600
+ if self.requires is not None:
601
+ self.requires.ensure(self.name, self.python)
602
+ loader = self._require_loader()
603
+ path = loader.path(self.script.uri)
604
+ if not path.is_file():
605
+ raise FileNotFoundError(f"Script {self.script.uri!s} not found at {path}")
606
+ return self.check(run_script(self.name, self.script_path, self.argv(path), self.render(state), path.parent,
607
+ self.timeout))