skillflow-py 1.4.2__tar.gz → 1.4.4__tar.gz

{skillflow_py-1.4.2 → skillflow_py-1.4.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: skillflow-py
-Version: 1.4.2
+Version: 1.4.4
 Summary: Config-agnostic LLM pipeline graph executor — turn skills into flows
 Author: Skillflow contributors
 License-Expression: MIT

{skillflow_py-1.4.2 → skillflow_py-1.4.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "skillflow-py"
-version = "1.4.2"
+version = "1.4.4"
 description = "Config-agnostic LLM pipeline graph executor — turn skills into flows"
 readme = "README.md"
 license = "MIT"

{skillflow_py-1.4.2 → skillflow_py-1.4.4}/src/skillflow/core.py

@@ -1286,29 +1286,44 @@ class SkillFlow:
                                      hook_name: str, items: list) -> dict:
         """Run a list of tool hooks in order (e.g. repo_apply then repo_delete).
 
-        Each item is a ``{'tool', 'params', 'on_failure'?}`` dict executed via
-        :meth:`_execute_tool_hook` (full variable resolution + project_root
-        injection). Per-item ``on_failure`` is honored: ``warn``/``skip`` log and
-        continue to the next item; ``retry``/``fail`` stop the sequence and
-        bubble up (carrying the item's ``on_failure``) so the caller applies the
-        right step-level outcome.
+        Each item is a ``{'tool', 'params', 'on_failure'?, 'max_retries'?}`` dict
+        executed via :meth:`_execute_tool_hook` (full variable resolution +
+        project_root injection). Per-item policy is honored IN PLACE:
+        ``on_failure: retry`` re-runs THAT item up to its own ``max_retries``
+        (without re-running earlier, already-succeeded items or the agent step);
+        ``warn``/``skip`` log and continue to the next item; ``fail`` (or a retry
+        item that exhausts its retries) stops the sequence and fails the step.
+        The sequence never bubbles ``retry`` to the caller — that would reset the
+        whole agent step and re-execute earlier, already-committed items.
         """
         detail_files = None
         for item in items:
             if not (isinstance(item, dict) and "tool" in item):
                 return {"passed": False,
                         "error": f"Invalid tool hook in '{hook_name}': {item!r}"}
-            res = self._execute_tool_hook(token, node, hook_name, item)
+            on_failure = item.get("on_failure", "fail")
+            max_retries = int(item.get("max_retries", 0) or 0)
+            res = {"passed": False}
+            for attempt in range(max_retries + 1):
+                res = self._execute_tool_hook(token, node, hook_name, item)
+                if res.get("passed", True):
+                    break
+                if on_failure == "retry" and attempt < max_retries:
+                    # Retry THIS item in place — do not re-run earlier items.
+                    self._emit_lifecycle_event(
+                        token, hook_name, "retry", res.get("error", ""))
+                    continue
+                break
             if not res.get("passed", True):
-                on_failure = item.get("on_failure", "fail")
                 if on_failure in ("warn", "skip"):
                     self._emit_lifecycle_event(
                         token, hook_name,
                         "warned" if on_failure == "warn" else "skipped",
                         res.get("error", ""))
                     continue
-                # retry / fail: stop and let the caller apply the step outcome.
-                return {**res, "on_failure": on_failure}
+                # 'fail', or a 'retry' item that exhausted max_retries → fail the
+                # step (never bubble 'retry', which re-runs the whole sequence).
+                return {**res, "on_failure": "fail"}
             files = res.get("files")
             if isinstance(files, list):
                 detail_files = files
@@ -2326,10 +2341,12 @@ class SkillFlow:
         so it retries promptly instead of stalling until its claim times out.
 
         Capped at 3 crashes: a tool that crashes deterministically is broken,
-        not transient, so relaunching it every tick just rampages until the
-        host's step-count valve trips. The SF-20 stale-recovery cap does NOT
-        cover this path (a crash reopens directly, never via
-        recover_stale_claims), so track the count here and fail after 3.
+        not transient. On the 3rd crash the RUN is failed (not just the step) —
+        marking only the step failed + current_node=NULL would let advance_run
+        re-resolve back to the tool and open a FRESH instance with a reset
+        counter, so the crash loop never actually stopped (only the host's
+        step-count valve caught it). The SF-20 stale-recovery cap does NOT cover
+        this path (a crash reopens directly, never via recover_stale_claims).
         """
         with self._tx() as conn:
             row = conn.execute(
@@ -2353,11 +2370,9 @@ class SkillFlow:
                     "claimed_by = NULL, updated_at = datetime('now') WHERE id = ?",
                     (error_msg, row["id"]),
                 )
-                conn.execute(
-                    "UPDATE skillflow_runs SET current_node = NULL, "
-                    "updated_at = datetime('now') WHERE id = ?",
-                    (run_id,),
-                )
+                # Fail the RUN so advance_run returns None instead of re-resolving
+                # the predecessor's transition and opening a fresh tool instance.
+                self._fail_run_in_tx(conn, run_id, error_msg)
                 self.notifications.publish_sync(
                     "step_failed",
                     {"run_id": run_id, "step_id": step_id,
@@ -2984,10 +2999,14 @@ class SkillFlow:
                 try:
                     node = self._get_resolver_for_run(
                         row["run_id"]).get_node(row["step_id"])
-                    if (node and node.step_type == "tool"
-                            and node.timeout_seconds
-                            and node.timeout_seconds > window):
-                        window = float(node.timeout_seconds)
+                    if node and node.step_type == "tool":
+                        if node.timeout_seconds == 0:
+                            # 0 = "no timeout": a live tool may run arbitrarily
+                            # long, so it is NEVER stale — reclaiming it would
+                            # relaunch it concurrently with itself (the rampage).
+                            continue
+                        if node.timeout_seconds > window:
+                            window = float(node.timeout_seconds)
                 except Exception:
                     pass
                 threshold = time.strftime(

{skillflow_py-1.4.2 → skillflow_py-1.4.4}/src/skillflow/graph.py

@@ -850,6 +850,15 @@ def _flags_match(match: dict, flags: dict, *,
             return False
         data = _parse_json_extract_last(content)
         if data is None:
+            # The file exists but no JSON value could be parsed out of it
+            # (e.g. an invalid \escape written by an agent). Without this
+            # log the run dies on "No matching transition ... flags {}"
+            # with no hint that the real problem is a syntax error.
+            import logging
+            logging.getLogger("skillflow.graph").warning(
+                "from_file match: '%s' exists but contains no parseable "
+                "JSON — transition treated as unmatched",
+                match["from_file"])
             return False
         return data.get(match["field"]) == match["value"]
 

{skillflow_py-1.4.2 → skillflow_py-1.4.4}/src/skillflow/write_tools.py

@@ -25,6 +25,7 @@ from __future__ import annotations
 
 import json
 import os
+import re
 from pathlib import Path
 
 
@@ -38,6 +39,95 @@ def _ensure_str(value, default: str = "") -> str:
     return json.dumps(value, ensure_ascii=False)
 
 
+# ── Structured JSON slots ────────────────────────────────────────────
+# A model asked to author a JSON document as a STRING inside tool-call JSON
+# must escape every backslash twice; under-escaping by one level (e.g. a
+# regex `/\.0$/` quoted in review feedback) produces a file that json.loads
+# rejects — and the run dies on an unmatched transition. For .json slots we
+# therefore move the document INTO the tool arguments, where the provider's
+# constrained decoding guarantees validity:
+#   tier 1 — the slot's `format` spec parses → one argument per field;
+#   tier 2 — no parseable format → a single `content` argument typed OBJECT;
+#   tier 3 — a string is still accepted but json.loads-validated at write
+#            time, returning an actionable tool error instead of writing a
+#            file no reader can parse.
+
+_TYPE_TOKENS = {
+    "bool": {"type": "boolean"},
+    "str": {"type": "string"},
+    "int": {"type": "integer"},
+    "float": {"type": "number"},
+    "num": {"type": "number"},
+}
+
+
+def _is_json_file(pattern: str) -> bool:
+    return pattern.lower().endswith(".json")
+
+
+def _format_value_to_spec(value) -> dict | None:
+    """Convert one parsed format value into a parameter spec, or None."""
+    if isinstance(value, str):
+        token = value[2:-2] if value.startswith("__") and value.endswith("__") else None
+        if token in _TYPE_TOKENS:
+            return dict(_TYPE_TOKENS[token])
+        # Free-text value = a string field described by that text
+        # (e.g. "description": "ONE-LINE summary (max 80 chars)").
+        return {"type": "string", "description": value}
+    if isinstance(value, list):
+        if len(value) != 1:
+            return None
+        items = _format_value_to_spec(value[0])
+        if items is None:
+            return None
+        return {"type": "array", "items": items}
+    if isinstance(value, dict):
+        props = {}
+        for k, v in value.items():
+            spec = _format_value_to_spec(v)
+            if spec is None:
+                return None
+            props[k] = spec
+        return {"type": "object", "properties": props}
+    return None
+
+
+def _parse_format_spec(format_spec) -> dict | None:
+    """Parse a pseudo-JSON ``format`` spec into per-field parameter specs.
+
+    ``'{"passed": bool, "feedback": str, "suggestions": [str, ...]}'``
+    → ``{"passed": {"type": "boolean"}, "feedback": {"type": "string"},
+        "suggestions": {"type": "array", "items": {"type": "string"}}}``
+
+    Returns None when the spec is absent or uses constructs the mini-DSL
+    can't resolve (e.g. a named shape like ``[subtask, ...]``) — callers
+    then fall back to a whole-document object parameter.
+    """
+    if not format_spec or not isinstance(format_spec, str):
+        return None
+    spec = format_spec.strip()
+    if not spec.startswith("{"):
+        return None
+    # ", ..." ellipses are illustrative — drop them
+    normalized = re.sub(r",\s*\.\.\.", "", spec)
+    # quote bare type tokens so the spec becomes valid JSON
+    normalized = re.sub(
+        r"\b(bool|str|int|float|num)\b", r'"__\1__"', normalized)
+    try:
+        data = json.loads(normalized)
+    except (json.JSONDecodeError, ValueError):
+        return None
+    if not isinstance(data, dict) or not data:
+        return None
+    props = {}
+    for key, value in data.items():
+        spec_v = _format_value_to_spec(value)
+        if spec_v is None:
+            return None
+        props[key] = spec_v
+    return props
+
+
 def _normalize_fixed_entry(value) -> dict:
     """Normalize a fixed output entry to {file, on_exists, format} dict."""
     if isinstance(value, str):
@@ -165,30 +255,71 @@ def generate_write_tool_schemas(output_mode: str,
             fmt_hint = f"\nExpected format: {format_spec.strip()}" if format_spec else ""
             is_glob = "*" in pattern
 
-            # Shared params
-            if is_glob:
-                id_desc = f"Replaces * in {pattern}"
-                # When the format declares an "id" field, the parameter value
-                # should match it — otherwise the LLM fills in a placeholder
-                # like "unknown" and all task cards land in the same file.
-                if format_spec and '"id"' in format_spec:
-                    id_desc += " — must equal the 'id' field value in your file content"
-                params = {
-                    "id": {"type": "string", "required": True,
-                           "description": id_desc},
-                    "content": {"type": "string", "required": True},
+            field_props = (_parse_format_spec(format_spec)
+                           if _is_json_file(pattern) else None)
+
+            if field_props:
+                # Tier 1 — one argument per document field: the model authors
+                # no JSON-in-a-string, so backslashes in field text can never
+                # produce an unparseable file.
+                params = {}
+                if is_glob and "id" not in field_props:
+                    params["id"] = {"type": "string", "required": True,
+                                    "description": f"Replaces * in {pattern}"}
+                for fname, fspec in field_props.items():
+                    p = dict(fspec)
+                    p["required"] = True
+                    if is_glob and fname == "id":
+                        extra = f"Replaces * in {pattern}; also written as the 'id' field."
+                        p["description"] = (
+                            f"{p.get('description', '')} {extra}".strip())
+                    params[fname] = p
+                create_params = dict(params)
+                write_hint = (fmt_hint + "\nProvide one argument per field — "
+                              "do NOT pass the document as a JSON-encoded string.")
+            elif _is_json_file(pattern):
+                # Tier 2 — whole document as a structured OBJECT argument
+                # (format absent or beyond the mini-DSL).
+                content_spec = {
+                    "type": "object", "required": True,
+                    "description": ("The complete JSON document as a structured "
+                                    "object — NOT a JSON-encoded string."),
                 }
+                if is_glob:
+                    id_desc = f"Replaces * in {pattern}"
+                    if format_spec and '"id"' in format_spec:
+                        id_desc += " — must equal the 'id' field value in your document"
+                    params = {
+                        "id": {"type": "string", "required": True,
+                               "description": id_desc},
+                        "content": content_spec,
+                    }
+                else:
+                    params = {"content": content_spec}
+                create_params = dict(params)
+                create_params["initialContent"] = create_params.pop("content")
+                write_hint = fmt_hint
             else:
-                params = {"content": {"type": "string", "required": True}}
-
-            create_params = dict(params)
-            if "content" in create_params:
+                # Text slots (md etc.) — plain string content, unchanged.
+                if is_glob:
+                    id_desc = f"Replaces * in {pattern}"
+                    if format_spec and '"id"' in format_spec:
+                        id_desc += " — must equal the 'id' field value in your file content"
+                    params = {
+                        "id": {"type": "string", "required": True,
+                               "description": id_desc},
+                        "content": {"type": "string", "required": True},
+                    }
+                else:
+                    params = {"content": {"type": "string", "required": True}}
+                create_params = dict(params)
                 create_params["initialContent"] = create_params.pop("content")
+                write_hint = fmt_hint
 
             # write_{slot} — full replace
             tools.append({
                 "name": f"write_{slot}",
-                "description": f"Replace {pattern} with new content.{fmt_hint}",
+                "description": f"Replace {pattern} with new content.{write_hint}",
                 "parameters": params,
             })
 
@@ -198,7 +329,7 @@ def generate_write_tool_schemas(output_mode: str,
                 "description": (
                     f"Create {pattern} with initial content. "
                     f"If file already exists, it is archived with a numeric suffix, "
-                    f"so {pattern} always holds the latest version.{fmt_hint}"
+                    f"so {pattern} always holds the latest version.{write_hint}"
                 ),
                 "parameters": create_params,
             })
@@ -241,6 +372,62 @@ def generate_write_tool_schemas(output_mode: str,
     return []
 
 
+def _resolve_slot_document(slot: str, fixed: dict, params: dict) -> "tuple[str | None, dict | None]":
+    """Resolve the text to write for a write_/create_{slot} call.
+
+    Returns ``(text, None)`` on success or ``(None, error_dict)`` — the error
+    goes back to the agent as the tool result, so it can self-correct within
+    the same step instead of a downstream reader choking on a bad file.
+
+    JSON slots accept three input shapes: per-field arguments (tier 1),
+    a structured object in content/initialContent (tier 2), or a raw string
+    that must survive ``json.loads`` (tier 3 — the legacy path that used to
+    write invalid escapes straight to disk). Non-JSON slots keep the legacy
+    string behaviour verbatim.
+    """
+    entry = fixed.get(slot)
+    normalized = _normalize_fixed_entry(entry) if entry is not None else {"file": ""}
+    pattern = normalized.get("file", "")
+
+    raw = params.get("content")
+    if raw is None or raw == "":
+        raw = params.get("initialContent")
+
+    if not _is_json_file(pattern):
+        return _ensure_str(raw, ""), None
+
+    field_props = _parse_format_spec(normalized.get("format"))
+    if field_props and raw is None:
+        doc, missing = {}, []
+        for fname in field_props:
+            if fname in params:
+                doc[fname] = params[fname]
+            else:
+                missing.append(fname)
+        if missing:
+            return None, {"error": (
+                f"{slot}: missing required field argument(s): "
+                f"{', '.join(missing)} — provide one argument per field "
+                f"of the document.")}
+        return json.dumps(doc, indent=2, ensure_ascii=False), None
+
+    if isinstance(raw, (dict, list)):
+        return json.dumps(raw, indent=2, ensure_ascii=False), None
+
+    if isinstance(raw, str) and raw.strip():
+        try:
+            json.loads(raw)
+        except json.JSONDecodeError as e:
+            return None, {"error": (
+                f"content for '{pattern}' is not valid JSON: {e}. Pass the "
+                f"document as structured arguments (or a plain object), not a "
+                f"JSON-encoded string; if you must pass a string, double every "
+                f"backslash (\\\\).")}
+        return raw, None
+
+    return None, {"error": f"{slot}: no content provided"}
+
+
 def resolve_write_target(slot: str, fixed: dict, params: dict) -> str:
     """Resolve the actual filename to write for a given write_* call."""
     entry = fixed.get(slot)
@@ -260,23 +447,27 @@ def execute_write(slot: str, fixed: dict, params: dict,
     directory = Path(output_dir)
     directory.mkdir(parents=True, exist_ok=True)
 
-    if mode == "new":
-        # Flipped rename: archive old file, write new content to canonical name
-        archived = _archive_old_file(directory, base_name)
-        filename = base_name
-    elif mode == "append":
+    if mode == "append":
         filename = base_name
         path = directory / filename
         content = _ensure_str(params.get("content", ""))
         existing = path.read_text(encoding="utf-8") if path.exists() else ""
         path.write_text(existing + content, encoding="utf-8")
         return {"written": filename}
-    else:  # replace
-        filename = base_name
 
+    # Resolve (and validate) the document BEFORE any archive rename, so a
+    # rejected write leaves the existing canonical file untouched.
+    content, err = _resolve_slot_document(slot, fixed, params)
+    if err:
+        return err
+
+    archived = None
+    if mode == "new":
+        # Flipped rename: archive old file, write new content to canonical name
+        archived = _archive_old_file(directory, base_name)
+    filename = base_name
     path = directory / filename
     path.parent.mkdir(parents=True, exist_ok=True)
-    content = _ensure_str(params.get("content") or params.get("initialContent", ""))
     path.write_text(content, encoding="utf-8")
     result = {"written": filename}
     if mode == "new" and archived:
@@ -290,10 +481,15 @@ def execute_create(slot: str, fixed: dict, params: dict,
     base_name = resolve_write_target(slot, fixed, params)
     directory = Path(output_dir)
     directory.mkdir(parents=True, exist_ok=True)
+    # Resolve (and validate) BEFORE archiving so a rejected write leaves the
+    # existing canonical file untouched.
+    content, err = _resolve_slot_document(slot, fixed, params)
+    if err:
+        return err
     archived = _archive_old_file(directory, base_name)
     path = directory / base_name
     path.parent.mkdir(parents=True, exist_ok=True)
-    path.write_text(_ensure_str(params.get("content") or params.get("initialContent", "")), encoding="utf-8")
+    path.write_text(content, encoding="utf-8")
     result = {"written": base_name}
     if archived:
         result["archived"] = archived

{skillflow_py-1.4.2 → skillflow_py-1.4.4}/src/skillflow_py.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: skillflow-py
-Version: 1.4.2
+Version: 1.4.4
 Summary: Config-agnostic LLM pipeline graph executor — turn skills into flows
 Author: Skillflow contributors
 License-Expression: MIT

{skillflow_py-1.4.2 → skillflow_py-1.4.4}/tests/test_core.py

@@ -1247,6 +1247,57 @@ def test_on_deliver_list_order_and_on_failure(sf: SkillFlow, tmp_path: Path,
     assert calls == []
 
 
+def test_on_deliver_item_retries_in_place(sf: SkillFlow, tmp_path: Path,
+                                          monkeypatch):
+    """A failing on_deliver item with on_failure=retry re-runs THAT item up to
+    its own max_retries IN PLACE; earlier items are not re-run, and the sequence
+    never bubbles 'retry' to the caller (which would reset the whole step)."""
+    sf._tool_loader = ToolLoader(
+        Path(__file__).parent.parent / "src" / "skillflow" / "tools")
+    sf._workspace = WorkspaceManager(str(tmp_path / "ws"),
+                                     projects_base=str(tmp_path / "proj"))
+    node = StepNode(id="s1", step_type="agent", output_mode="content",
+                    output_fixed={"out": "r.md"}, transitions=[Transition(to=None)])
+    sf.register_graph(PipelineGraph(name="seq", begin="s1", steps=[node]))
+    rid = sf.create_run("seq", {"project_id": "pid"})
+    sf.start_run(rid)
+    sf.advance_run(rid)
+    token = sf.claim_next_step(rid).token
+
+    calls: list = []
+
+    # 'flaky' fails its first 2 attempts, succeeds on the 3rd.
+    def fake(tok, nd, hook_name, spec):
+        calls.append(spec["tool"])
+        if spec["tool"] == "flaky":
+            return {"passed": calls.count("flaky") >= 3}
+        return {"passed": True}
+    monkeypatch.setattr(sf, "_execute_tool_hook", fake)
+
+    r = sf._execute_lifecycle_hook(token, node, "on_deliver", [
+        {"tool": "repo_apply"},
+        {"tool": "flaky", "on_failure": "retry", "max_retries": 3},
+    ])
+    # repo_apply ran ONCE (not re-run while flaky retried); flaky retried in place.
+    assert calls == ["repo_apply", "flaky", "flaky", "flaky"]
+    assert r["passed"] is True
+
+    # Exhausted retries → fail the STEP, never bubble 'retry'.
+    calls.clear()
+
+    def always_fail(tok, nd, hook_name, spec):
+        calls.append(spec["tool"])
+        return {"passed": spec["tool"] != "boom"}
+    monkeypatch.setattr(sf, "_execute_tool_hook", always_fail)
+    r = sf._execute_lifecycle_hook(token, node, "on_deliver", [
+        {"tool": "repo_apply"},
+        {"tool": "boom", "on_failure": "retry", "max_retries": 2},
+    ])
+    assert calls == ["repo_apply", "boom", "boom", "boom"]  # 1 initial + 2 retries
+    assert r["passed"] is False
+    assert r.get("on_failure") == "fail"   # NOT "retry" — no whole-step re-run
+
+
 # ── Durable run trace ─────────────────────────────────────────────────
 
 def test_trace_append_and_get(sf: SkillFlow):

{skillflow_py-1.4.2 → skillflow_py-1.4.4}/tests/test_recovery.py

@@ -1,17 +1,84 @@
 """Unit tests for recovery.py."""
 
 import time
+from pathlib import Path
 
 import pytest
 
 from skillflow.core import SkillFlow
 from skillflow.graph import PipelineGraph, StepNode, Transition
+from skillflow.tool_loader import ToolLoader
+from skillflow.workspace import WorkspaceManager
+
+_REAL_TOOLS = Path(__file__).parent.parent / "src" / "skillflow" / "tools"
 
 
 def _agent(id: str, transitions=None):
     return StepNode(id=id, step_type="agent", transitions=transitions or [])
 
 
+def test_recover_never_reclaims_tool_with_zero_timeout(sf: SkillFlow):
+    """A tool node with timeout_seconds=0 ('no timeout') is never reclaimed,
+    however old the claim — reclaiming a live no-timeout tool would relaunch it
+    concurrently with itself (the rampage)."""
+    graph = PipelineGraph(
+        name="test", begin="a",
+        steps=[StepNode(id="a", step_type="tool", tool_name="write",
+                        timeout_seconds=0, transitions=[])],
+    )
+    sf.register_graph(graph)
+    run_id = sf.create_run("test")
+    sf.start_run(run_id)
+    long_ago = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime(time.time() - 99999))
+    with sf._lock:
+        sf._conn.execute(
+            "INSERT INTO skillflow_steps (run_id, step_id, step_config_json, "
+            "inputs_json, max_retries, status, claimed_at, created_at, updated_at) "
+            "VALUES (?, 'a', '{}', '{}', 3, 'claimed', ?, "
+            "datetime('now'), datetime('now'))",
+            (run_id, long_ago))
+        sf._conn.commit()
+    # Claimed 99999s ago, but timeout_seconds=0 → never stale.
+    assert sf.recover_stale_claims(stale_threshold_seconds=60) == []
+    st = sf._conn.execute(
+        "SELECT status FROM skillflow_steps WHERE run_id=? AND step_id='a' "
+        "ORDER BY id DESC LIMIT 1", (run_id,)).fetchone()
+    assert st["status"] == "claimed"
+
+
+def test_tool_crash_fails_run_after_three(sf: SkillFlow, tmp_path,
+                                          monkeypatch):
+    """A tool that crashes on EVERY execution fails the RUN after 3 crashes,
+    instead of looping forever via advance_run re-resolving into fresh instances
+    (regression: the per-instance _tool_reopen_count was reset each time
+    _claim_tool_step_in_tx opened a new instance)."""
+    sf._tool_loader = ToolLoader(_REAL_TOOLS)
+    sf._workspace = WorkspaceManager(str(tmp_path / "ws"),
+                                     projects_base=str(tmp_path / "proj"))
+    node = StepNode(id="boom", step_type="tool", tool_name="write",
+                    transitions=[Transition(to=None)])
+    sf.register_graph(PipelineGraph(name="crash", begin="boom", steps=[node]))
+    run_id = sf.create_run("crash", {"project_id": "p"})
+    sf.start_run(run_id)
+
+    def _boom(*a, **k):
+        raise RuntimeError("boom")
+    monkeypatch.setattr(sf, "_execute_tool_inline", _boom)
+
+    for _ in range(25):
+        try:
+            sf.advance_run(run_id)   # tool fast-path reopens then re-raises
+        except RuntimeError:
+            pass
+        if sf.get_run(run_id)["status"] == "failed":
+            break
+    assert sf.get_run(run_id)["status"] == "failed"
+    n = sf._conn.execute(
+        "SELECT COUNT(*) c FROM skillflow_steps WHERE run_id=? AND step_id='boom'",
+        (run_id,)).fetchone()["c"]
+    assert n == 1, f"crash should fail the run after 1 instance x3, got {n}"
+
+
 def test_recover_respects_tool_timeout_seconds(sf: SkillFlow):
     """A TOOL step claimed longer than the flat threshold but WITHIN its
     timeout_seconds is NOT reclaimed — a slow-but-alive tool (run_tests,

{skillflow_py-1.4.2 → skillflow_py-1.4.4}/tests/test_write_tools.py

@@ -232,11 +232,12 @@ class TestWriteTools:
             desc = tool["description"]
             assert "Expected format:" in desc
             assert '{"id": str, "description": str}' in desc
-        # id param description links to content's id field when format has "id"
+        # Structured slot: the id argument IS the content's id field — the
+        # coupling is structural now, not a prompt-hint plea.
         write_tool = next(t for t in schemas if t["name"] == "write_task_card")
         id_desc = write_tool["parameters"]["id"]["description"]
         assert "Replaces * in tasks/*.json" in id_desc
-        assert "must equal the 'id' field value" in id_desc
+        assert "also written as the 'id' field" in id_desc
 
     def test_glob_id_param_without_id_in_format(self):
         """When format lacks 'id', the id param description stays plain."""
@@ -257,3 +258,172 @@ class TestWriteTools:
         # String entry omits format
         result = _normalize_fixed_entry("x.json")
         assert "format" not in result
+
+
+VERDICT_FIXED = {
+    "verdict": {"file": "review_verdict.json", "on_exists": "new",
+                "format": '{"passed": bool, "feedback": str, "suggestions": [str, ...]}'}
+}
+
+
+class TestStructuredJsonSlots:
+    """Structured .json slots: the document rides inside the tool arguments,
+    so JSON-in-a-string double-escaping (the review_verdict '\\.' incident)
+    is structurally impossible — and a string fallback is validated."""
+
+    # ── format-spec parser ──────────────────────────────────────
+
+    def test_parse_format_verdict(self):
+        from skillflow.write_tools import _parse_format_spec
+        props = _parse_format_spec(
+            '{"passed": bool, "feedback": str, "suggestions": [str, ...]}')
+        assert props == {
+            "passed": {"type": "boolean"},
+            "feedback": {"type": "string"},
+            "suggestions": {"type": "array", "items": {"type": "string"}},
+        }
+
+    def test_parse_format_nested_arrays(self):
+        from skillflow.write_tools import _parse_format_spec
+        props = _parse_format_spec('{"execution_order": [[str, ...], ...]}')
+        assert props == {"execution_order": {
+            "type": "array", "items": {"type": "array",
+                                       "items": {"type": "string"}}}}
+
+    def test_parse_format_prose_becomes_description(self):
+        from skillflow.write_tools import _parse_format_spec
+        props = _parse_format_spec(
+            '{"id": str, "description": "ONE-LINE summary (max 80 chars)"}')
+        assert props["description"] == {
+            "type": "string",
+            "description": "ONE-LINE summary (max 80 chars)"}
+
+    def test_parse_format_named_shape_unparseable(self):
+        from skillflow.write_tools import _parse_format_spec
+        # References a named shape the mini-DSL can't resolve → None (tier 2)
+        assert _parse_format_spec(
+            '{"subtasks": [subtask, ...], "execution_order": [[str, ...], ...]}'
+        ) is None
+
+    def test_parse_format_non_object(self):
+        from skillflow.write_tools import _parse_format_spec
+        assert _parse_format_spec("free prose format") is None
+        assert _parse_format_spec(None) is None
+        assert _parse_format_spec("") is None
+
+    # ── schema generation tiers ─────────────────────────────────
+
+    def test_tier1_per_field_params(self):
+        schemas = generate_write_tool_schemas("content", VERDICT_FIXED)
+        create = next(s for s in schemas if s["name"] == "create_verdict")
+        assert set(create["parameters"]) == {"passed", "feedback", "suggestions"}
+        assert create["parameters"]["passed"] == {
+            "type": "boolean", "required": True}
+        assert create["parameters"]["suggestions"]["items"] == {"type": "string"}
+        # no stringly content params anywhere
+        assert "content" not in create["parameters"]
+        assert "initialContent" not in create["parameters"]
+        assert "do NOT pass the document as a JSON-encoded string" in create["description"]
+        # edit stays textual (surgical string replace)
+        edit = next(s for s in schemas if s["name"] == "edit_verdict")
+        assert set(edit["parameters"]) == {"old_str", "new_str"}
+
+    def test_tier2_object_content_when_format_unparseable(self):
+        schemas = generate_write_tool_schemas("content", {
+            "manifest": {"file": "subtasks_manifest.json",
+                         "format": '{"subtasks": [subtask, ...]}'}
+        })
+        write = next(s for s in schemas if s["name"] == "write_manifest")
+        assert write["parameters"]["content"]["type"] == "object"
+        create = next(s for s in schemas if s["name"] == "create_manifest")
+        assert create["parameters"]["initialContent"]["type"] == "object"
+
+    def test_tier3_text_slot_unchanged(self):
+        schemas = generate_write_tool_schemas("content", {
+            "notes": {"file": "research_notes.md", "format": "prose format"}
+        })
+        write = next(s for s in schemas if s["name"] == "write_notes")
+        assert write["parameters"]["content"] == {"type": "string",
+                                                  "required": True}
+
+    # ── executor: per-field assembly ────────────────────────────
+
+    def test_create_assembles_document_from_fields(self, tmp_path):
+        from skillflow.write_tools import execute_create
+        import json as _json
+        res = execute_create("verdict", VERDICT_FIXED, {
+            "passed": True,
+            "feedback": r"the `.replace(/\.0$/, '')` fix is correct",
+            "suggestions": [],
+        }, str(tmp_path))
+        assert res == {"written": "review_verdict.json"}
+        data = _json.loads((tmp_path / "review_verdict.json").read_text())
+        # The backslash that used to kill the run survives intact
+        assert data["passed"] is True
+        assert "\\.0$" in data["feedback"]
+
+    def test_create_missing_field_is_tool_error(self, tmp_path):
+        from skillflow.write_tools import execute_create
+        res = execute_create("verdict", VERDICT_FIXED,
+                             {"passed": True}, str(tmp_path))
+        assert "missing required field" in res["error"]
+        assert not (tmp_path / "review_verdict.json").exists()
+
+    def test_create_accepts_object_content(self, tmp_path):
+        from skillflow.write_tools import execute_create
+        import json as _json
+        res = execute_create("verdict", VERDICT_FIXED, {
+            "initialContent": {"passed": False, "feedback": "x",
+                               "suggestions": ["y"]},
+        }, str(tmp_path))
+        assert res == {"written": "review_verdict.json"}
+        data = _json.loads((tmp_path / "review_verdict.json").read_text())
+        assert data["passed"] is False
+
+    def test_create_validates_string_content(self, tmp_path):
+        from skillflow.write_tools import execute_create
+        # The exact incident: an under-escaped backslash in a JSON string
+        bad = '{"passed": true, "feedback": "regex /\\.0$/ ok", "suggestions": []}'
+        assert "\\." in bad  # single backslash-dot → invalid JSON escape
+        res = execute_create("verdict", VERDICT_FIXED,
+                             {"initialContent": bad}, str(tmp_path))
+        assert "not valid JSON" in res["error"]
+        assert not (tmp_path / "review_verdict.json").exists()
+
+    def test_create_valid_string_still_accepted(self, tmp_path):
+        from skillflow.write_tools import execute_create
+        good = '{"passed": true, "feedback": "ok", "suggestions": []}'
+        res = execute_create("verdict", VERDICT_FIXED,
+                             {"initialContent": good}, str(tmp_path))
+        assert res == {"written": "review_verdict.json"}
+
+    def test_rejected_write_preserves_existing_file(self, tmp_path):
+        from skillflow.write_tools import execute_create
+        (tmp_path / "review_verdict.json").write_text('{"passed": false}')
+        res = execute_create("verdict", VERDICT_FIXED,
+                             {"initialContent": "{invalid"}, str(tmp_path))
+        assert "error" in res
+        # on_exists:new must NOT have archived the old file on a rejected write
+        assert (tmp_path / "review_verdict.json").read_text() == '{"passed": false}'
+        assert not (tmp_path / "review_verdict_1.json").exists()
+
+    def test_glob_id_fills_filename_and_field(self, tmp_path):
+        from skillflow.write_tools import execute_write
+        import json as _json
+        fixed = {"task_card": {"file": "tasks/*.json",
+                               "format": '{"id": str, "description": str}'}}
+        res = execute_write("task_card", fixed, {
+            "id": "core_lib", "description": "build the core library",
+        }, str(tmp_path))
+        assert res == {"written": "tasks/core_lib.json"}
+        data = _json.loads((tmp_path / "tasks/core_lib.json").read_text())
+        assert data == {"id": "core_lib",
+                        "description": "build the core library"}
+
+    def test_text_slot_write_unchanged(self, tmp_path):
+        from skillflow.write_tools import execute_write
+        res = execute_write("notes", {"notes": "research_notes.md"},
+                            {"content": "plain text with \\. backslash"},
+                            str(tmp_path))
+        assert res == {"written": "research_notes.md"}
+        assert "\\." in (tmp_path / "research_notes.md").read_text()