skillflow-py 1.2.0__tar.gz → 1.2.1__tar.gz

{skillflow_py-1.2.0/src/skillflow_py.egg-info → skillflow_py-1.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: skillflow-py
-Version: 1.2.0
+Version: 1.2.1
 Summary: Config-agnostic LLM pipeline graph executor — turn skills into flows
 Author: Skillflow contributors
 License-Expression: MIT
@@ -207,10 +207,15 @@ This powers both **inner review loops** (e.g. `review → implement`, `max_loop:
 context:
   - source: { step: "1" }
   - source: { step: "2", mode: "interfaces" }
-  - source: { config: "meta", output: "brief.md" }
+  - source: { config: "meta", output: "brief.md" }                  # any step of another config
+  - source: { config: "meta", step: "finalize", output: "x.json" }  # a SPECIFIC step's output
   - source: { tool: "dir_tree" }
 ```
 
+A cross-config source without `step` scans the other config's step dirs for the
+file; adding `step` reads that one step's output (use it when only a specific
+producing step is authoritative).
+
 ## Checkpoints
 
 Agent steps can pause for human approval (`tests/fixtures/checkpoint_cycle.yaml`). On reject, the feedback is injected (via the `_feedback` channel) so the re-run knows *why* it was rejected:
@@ -268,6 +273,8 @@ end_conditions:
     - type: node_reached
       node: "5_review"
       result: "completed"
+      require_completed: true   # fire only once the node has COMPLETED, not merely
+                                # been reached (i.e. become current_node)
     - type: max_total_steps
       limit: 200
     - type: max_run_duration_seconds
@@ -276,6 +283,17 @@ end_conditions:
       flag: { fatal_error: true }
 ```
 
+`require_completed` (node_reached only) gates termination on the node's step
+reaching `completed` status. Use it when the terminal node is a real agent/tool
+step that must execute before the run ends — without it the condition fires as
+soon as the node becomes `current_node`.
+
+**Terminating a run needs an end condition.** A transition `to: null` does NOT by
+itself end a run: with no resolvable target the run is marked **failed** ("no
+matching transition"). To finish cleanly, give the terminal step `to: null` **and**
+a `node_reached` end condition for that node (the pattern above). This applies to
+`tool` and `gate` steps too, not just `agent` steps.
+
 ## Stale Claim Recovery
 
 Built into `advance_run`. A claim whose worker died before calling `confirm`, and that is older than `stale_threshold_seconds` (default 300), is auto-reset to `pending` and re-claimed:

{skillflow_py-1.2.0 → skillflow_py-1.2.1}/README.md

@@ -183,10 +183,15 @@ This powers both **inner review loops** (e.g. `review → implement`, `max_loop:
 context:
   - source: { step: "1" }
   - source: { step: "2", mode: "interfaces" }
-  - source: { config: "meta", output: "brief.md" }
+  - source: { config: "meta", output: "brief.md" }                  # any step of another config
+  - source: { config: "meta", step: "finalize", output: "x.json" }  # a SPECIFIC step's output
   - source: { tool: "dir_tree" }
 ```
 
+A cross-config source without `step` scans the other config's step dirs for the
+file; adding `step` reads that one step's output (use it when only a specific
+producing step is authoritative).
+
 ## Checkpoints
 
 Agent steps can pause for human approval (`tests/fixtures/checkpoint_cycle.yaml`). On reject, the feedback is injected (via the `_feedback` channel) so the re-run knows *why* it was rejected:
@@ -244,6 +249,8 @@ end_conditions:
     - type: node_reached
       node: "5_review"
       result: "completed"
+      require_completed: true   # fire only once the node has COMPLETED, not merely
+                                # been reached (i.e. become current_node)
     - type: max_total_steps
       limit: 200
     - type: max_run_duration_seconds
@@ -252,6 +259,17 @@ end_conditions:
       flag: { fatal_error: true }
 ```
 
+`require_completed` (node_reached only) gates termination on the node's step
+reaching `completed` status. Use it when the terminal node is a real agent/tool
+step that must execute before the run ends — without it the condition fires as
+soon as the node becomes `current_node`.
+
+**Terminating a run needs an end condition.** A transition `to: null` does NOT by
+itself end a run: with no resolvable target the run is marked **failed** ("no
+matching transition"). To finish cleanly, give the terminal step `to: null` **and**
+a `node_reached` end condition for that node (the pattern above). This applies to
+`tool` and `gate` steps too, not just `agent` steps.
+
 ## Stale Claim Recovery
 
 Built into `advance_run`. A claim whose worker died before calling `confirm`, and that is older than `stale_threshold_seconds` (default 300), is auto-reset to `pending` and re-claimed:

{skillflow_py-1.2.0 → skillflow_py-1.2.1}/pyproject.toml

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

{skillflow_py-1.2.0 → skillflow_py-1.2.1}/src/skillflow/core.py

@@ -1817,16 +1817,20 @@ class SkillFlow:
             items = flat
         return items, False
 
-    def _reset_loop_body_edge_counts(self, conn, run_id, resolver,
-                                     loop_step_id, body_target):
-        """Clear edge counts for the loop body so each iteration gets a fresh
-        retry budget.
-
-        Inner review/verify loops (e.g. t_impl_review→t_impl, max_loop=3) are
-        counted per (run, from, to) — i.e. shared across every iteration. That
-        starves later tasks of retries. Resetting the body's edge counts when a
-        new item is dispatched scopes the budget to the current iteration.
+    def _loop_body_nodes(self, resolver, loop_step_id) -> set[str]:
+        """The set of node ids that form a loop's body: reachable from the
+        loop's body transition, following transitions, excluding the loop node
+        itself. Purely topological — derived from the graph, no config-specific
+        names — so it stays config-agnostic.
         """
+        node = resolver.get_node(loop_step_id)
+        if not node:
+            return set()
+        body_target = None
+        for t in node.transitions:
+            if t.to:
+                body_target = t.to
+                break
         body_nodes: set[str] = set()
         stack = [body_target]
         while stack:
@@ -1834,12 +1838,25 @@ class SkillFlow:
             if not nid or nid in body_nodes or nid == loop_step_id:
                 continue
             body_nodes.add(nid)
-            node = resolver.get_node(nid)
-            if not node:
+            n = resolver.get_node(nid)
+            if not n:
                 continue
-            for t in node.transitions:
+            for t in n.transitions:
                 if t.to and t.to != loop_step_id:
                     stack.append(t.to)
+        return body_nodes
+
+    def _reset_loop_body_edge_counts(self, conn, run_id, resolver,
+                                     loop_step_id, body_target):
+        """Clear edge counts for the loop body so each iteration gets a fresh
+        retry budget.
+
+        Inner review/verify loops (e.g. t_impl_review→t_impl, max_loop=3) are
+        counted per (run, from, to) — i.e. shared across every iteration. That
+        starves later tasks of retries. Resetting the body's edge counts when a
+        new item is dispatched scopes the budget to the current iteration.
+        """
+        body_nodes = self._loop_body_nodes(resolver, loop_step_id)
         if not body_nodes:
             return
         placeholders = ",".join("?" for _ in body_nodes)
@@ -1849,6 +1866,38 @@ class SkillFlow:
             (run_id, *sorted(body_nodes)),
         )
 
+    def _credit_loop_current_item(self, conn, run_id: str, loop_step_id: str) -> None:
+        """Progression (write): mark the loop's current_item completed.
+
+        Called from confirm_step when a body cycle's terminal step routes back to
+        the loop node — exactly once per completed body cycle, atomic with the
+        terminal step's completion. _resolve_loop performs NO crediting (it only
+        reads completed_items to pick the next item), so resolution is idempotent
+        and the separate advance/claim transactions can't cause a spurious
+        advance or skipped item.
+        """
+        row = conn.execute(
+            "SELECT completed_items, current_item FROM skillflow_loop_state "
+            "WHERE run_id = ? AND loop_step_id = ?",
+            (run_id, loop_step_id),
+        ).fetchone()
+        if not row or not row["current_item"]:
+            return
+        completed: set[str] = set()
+        if row["completed_items"]:
+            try:
+                completed = set(self._deserialize(row["completed_items"]))
+            except Exception:
+                pass
+        if row["current_item"] in completed:
+            return  # idempotent — already credited
+        completed.add(row["current_item"])
+        conn.execute(
+            "UPDATE skillflow_loop_state SET completed_items = ?, "
+            "updated_at = datetime('now') WHERE run_id = ? AND loop_step_id = ?",
+            (self._serialize(sorted(completed)), run_id, loop_step_id),
+        )
+
     def _resolve_loop(self, conn, run: dict, resolver, loop_step_id: str) -> str | None:
         """Resolve a loop step to either its body or done transition.
 
@@ -1907,42 +1956,25 @@ class SkillFlow:
                     return t.to
             return None
 
-        # ── Completed set ────────────────────────────────────────────────
+        # ── Completed set — scoped to the LIVE manifest ───────────────────
+        # Resolution is READ-ONLY w.r.t. progression: it never credits
+        # completion (confirm_step does that via _credit_loop_current_item when a
+        # body cycle returns to the loop). So re-entry — e.g. an extra scheduler
+        # tick in the dispatch→claim gap — re-picks the SAME item with
+        # current_item unchanged, never spuriously advancing or skipping work.
         completed: set[str] = set()
-        prev_item: str | None = None
+        current_item: str | None = None
         if row:
             if row["completed_items"]:
                 try:
                     completed = set(self._deserialize(row["completed_items"]))
                 except Exception:
                     pass
-            prev_item = row["current_item"] or None
-        # Backward compat: old rows with current_index (no completed_items).
-        # current_index points to the LAST DISPATCHED item.
-        # Items BEFORE current_index are completed; items[current_index] is
-        # the currently-executing item.  Only reconstruct prev_item when at
-        # least one item has finished (so we have a "previously dispatched"
-        # item to mark completed).
-        if not completed and row and row["current_item"] is None:
-            try:
-                old_items = self._deserialize(row["items_json"]) if row["items_json"] else []
-                old_idx = row["current_index"]
-                if isinstance(old_idx, int) and old_idx > 0:
-                    completed = set(old_items[:old_idx])
-                    if old_idx < len(old_items):
-                        prev_item = old_items[old_idx]
-                elif isinstance(old_idx, int) and old_idx == 0:
-                    pass  # first dispatch — nothing completed, nothing to mark
-            except Exception:
-                pass
-
-        # Mark the previously-dispatched item as completed.
-        # prev_item is None on the very first dispatch (row is None),
-        # so nothing is marked. On every subsequent entry, prev_item
-        # was set by the previous dispatch and has now finished.
-        if prev_item and prev_item not in completed:
-            completed.add(prev_item)
-            prev_item = None
+            current_item = row["current_item"] or None
+        # Drop superseded names from prior goal-loop rounds so completed_items
+        # reflects only the active manifest (prevents the len(completed) overcount
+        # and the scheduler's idx-out-of-range).
+        completed &= set(items)
 
         if row is None:
             if not items:
@@ -1955,13 +1987,6 @@ class SkillFlow:
                 (run["id"], loop_step_id, self._serialize(items),
                  loop_cfg.item_as or "loop_item"),
             )
-        else:
-            # Always persist the live manifest so context resolution sees it
-            conn.execute(
-                "UPDATE skillflow_loop_state SET items_json = ?, "
-                "updated_at = datetime('now') WHERE run_id = ? AND loop_step_id = ?",
-                (self._serialize(items), run["id"], loop_step_id),
-            )
 
         # ── Find first uncompleted item (manifest order) ────────────────
         if not items:
@@ -1974,17 +1999,23 @@ class SkillFlow:
         if next_item is None:
             return _route_done()
 
-        # ── Dispatch ─────────────────────────────────────────────────────
+        # ── Dispatch (idempotent) ─────────────────────────────────────────
+        # Persist the live manifest + scoped completed set + the item to run.
+        new_dispatch = (next_item != current_item)
         conn.execute(
-            "UPDATE skillflow_loop_state SET completed_items = ?, "
+            "UPDATE skillflow_loop_state SET items_json = ?, completed_items = ?, "
             "current_item = ?, updated_at = datetime('now') "
             "WHERE run_id = ? AND loop_step_id = ?",
-            (self._serialize(sorted(completed)), next_item,
-             run["id"], loop_step_id),
-        )
-        self._reset_loop_body_edge_counts(
-            conn, run["id"], resolver, loop_step_id, body_target
+            (self._serialize(items), self._serialize(sorted(completed)),
+             next_item, run["id"], loop_step_id),
         )
+        # Reset the body's per-iteration retry budget ONLY for a genuinely new
+        # item — never on an idempotent re-entry for the same in-flight item,
+        # which would wipe the body's mid-cycle edge counts.
+        if new_dispatch:
+            self._reset_loop_body_edge_counts(
+                conn, run["id"], resolver, loop_step_id, body_target
+            )
         return body_target
 
     def _resolve_next_in_tx(self, conn, run_id: str, step_id: str,
@@ -2043,7 +2074,19 @@ class SkillFlow:
                 tool_node = resolver.get_node(t.to)
                 if tool_node and not self._should_delegate_tool(tool_node.tool_name):
                     skip_tool = True
-            if resolver.is_gate(t.to) or resolver.is_loop(t.to) or skip_tool:
+            if resolver.is_loop(t.to):
+                # PROGRESSION: credit the loop's current_item — but ONLY when
+                # THIS completing step is inside the loop body (a body cycle
+                # returning). An EXTERNAL step transitioning INTO the loop
+                # (entry / goal-loop re-entry) must NOT credit: that would mark
+                # the in-flight item complete and skip it. Topological check
+                # (no config-specific names). Fires once per body cycle; a stray
+                # re-tick at the loop node goes through advance_run only (no
+                # credit), so resolution stays idempotent.
+                if step_id in self._loop_body_nodes(resolver, t.to):
+                    self._credit_loop_current_item(conn, run_id, t.to)
+                return None
+            if resolver.is_gate(t.to) or skip_tool:
                 return None
 
             # Check max_loop on this edge
@@ -3111,6 +3154,11 @@ class SkillFlow:
         kwargs = dict(params)
         kwargs.setdefault("workspace_root", project_root or "")
         kwargs.setdefault("project_root", project_root or "")
+        # Forward step/run identity so tools that want per-step state (e.g.
+        # scratch-file tools) can isolate by step. Signature-filtered below, so
+        # tools that don't declare these params are unaffected.
+        kwargs.setdefault("step_id", step_id or "")
+        kwargs.setdefault("run_id", run_id or "")
         # SF-10: pass step staging/output dirs so read_file (and similar tools)
         # can find files the agent just wrote (in .tmp) or files from previous
         # retries (in the step's final dir). write_* tools write to .tmp; without

{skillflow_py-1.2.0 → skillflow_py-1.2.1/src/skillflow_py.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: skillflow-py
-Version: 1.2.0
+Version: 1.2.1
 Summary: Config-agnostic LLM pipeline graph executor — turn skills into flows
 Author: Skillflow contributors
 License-Expression: MIT
@@ -207,10 +207,15 @@ This powers both **inner review loops** (e.g. `review → implement`, `max_loop:
 context:
   - source: { step: "1" }
   - source: { step: "2", mode: "interfaces" }
-  - source: { config: "meta", output: "brief.md" }
+  - source: { config: "meta", output: "brief.md" }                  # any step of another config
+  - source: { config: "meta", step: "finalize", output: "x.json" }  # a SPECIFIC step's output
   - source: { tool: "dir_tree" }
 ```
 
+A cross-config source without `step` scans the other config's step dirs for the
+file; adding `step` reads that one step's output (use it when only a specific
+producing step is authoritative).
+
 ## Checkpoints
 
 Agent steps can pause for human approval (`tests/fixtures/checkpoint_cycle.yaml`). On reject, the feedback is injected (via the `_feedback` channel) so the re-run knows *why* it was rejected:
@@ -268,6 +273,8 @@ end_conditions:
     - type: node_reached
       node: "5_review"
       result: "completed"
+      require_completed: true   # fire only once the node has COMPLETED, not merely
+                                # been reached (i.e. become current_node)
     - type: max_total_steps
       limit: 200
     - type: max_run_duration_seconds
@@ -276,6 +283,17 @@ end_conditions:
       flag: { fatal_error: true }
 ```
 
+`require_completed` (node_reached only) gates termination on the node's step
+reaching `completed` status. Use it when the terminal node is a real agent/tool
+step that must execute before the run ends — without it the condition fires as
+soon as the node becomes `current_node`.
+
+**Terminating a run needs an end condition.** A transition `to: null` does NOT by
+itself end a run: with no resolvable target the run is marked **failed** ("no
+matching transition"). To finish cleanly, give the terminal step `to: null` **and**
+a `node_reached` end condition for that node (the pattern above). This applies to
+`tool` and `gate` steps too, not just `agent` steps.
+
 ## Stale Claim Recovery
 
 Built into `advance_run`. A claim whose worker died before calling `confirm`, and that is older than `stale_threshold_seconds` (default 300), is auto-reset to `pending` and re-claimed:

{skillflow_py-1.2.0 → skillflow_py-1.2.1}/tests/test_integration_configs.py

@@ -511,6 +511,123 @@ def test_loop_flat_list(sf_with_workspace):
     assert items == ["one", "two"]
 
 
+def test_resolve_loop_idempotent_without_body_completion(sf_with_workspace):
+    """Re-entering _resolve_loop WITHOUT the body completing must re-pick the
+    SAME item and credit nothing — resolution is read-only w.r.t. progression.
+
+    Regression: the old code credited current_item on every entry, so a stray
+    re-resolve in the dispatch->claim gap skipped items and churned the body
+    claim (the version-15 / 7-claim behavior in the wild).
+    """
+    import json
+    sf = sf_with_workspace
+    run_id = _loop_prepare(sf, [["a", "b", "c"]])
+    resolver = sf._get_resolver_for_run(run_id)
+
+    def _resolve():
+        with sf._tx() as conn:
+            run = conn.execute("SELECT * FROM skillflow_runs WHERE id = ?",
+                               (run_id,)).fetchone()
+            return sf._resolve_loop(conn, run, resolver, "task_iterator")
+
+    def _state():
+        with sf._tx() as conn:
+            r = conn.execute("SELECT completed_items, current_item FROM "
+                             "skillflow_loop_state WHERE run_id = ?",
+                             (run_id,)).fetchone()
+            return json.loads(r["completed_items"] or "[]"), r["current_item"]
+
+    t1 = _resolve(); comp1, cur1 = _state()
+    t2 = _resolve(); comp2, cur2 = _state()   # re-entry, body never ran
+    t3 = _resolve(); comp3, cur3 = _state()
+    assert t1 == t2 == t3 == "process_task"
+    assert cur1 == cur2 == cur3 == "a"        # same item every time
+    assert comp1 == comp2 == comp3 == []      # nothing credited on resolution
+
+
+def test_loop_completed_scoped_to_live_manifest(sf_with_workspace):
+    """completed_items is intersected with the live manifest on each resolve, so
+    superseded names from a prior goal-loop round are dropped (no overcount)."""
+    import json
+    sf = sf_with_workspace
+    run_id = _loop_prepare(sf, [["a", "b"]])
+    resolver = sf._get_resolver_for_run(run_id)
+    with sf._tx() as conn:  # first resolve creates the row + dispatches "a"
+        run = conn.execute("SELECT * FROM skillflow_runs WHERE id = ?",
+                           (run_id,)).fetchone()
+        sf._resolve_loop(conn, run, resolver, "task_iterator")
+    with sf._tx() as conn:  # inject a stale name not in the manifest
+        conn.execute("UPDATE skillflow_loop_state SET completed_items = ? "
+                     "WHERE run_id = ?",
+                     (json.dumps(["a", "stale_old_task"]), run_id))
+    with sf._tx() as conn:  # re-resolve: stale dropped, next item is "b"
+        run = conn.execute("SELECT * FROM skillflow_runs WHERE id = ?",
+                           (run_id,)).fetchone()
+        nxt = sf._resolve_loop(conn, run, resolver, "task_iterator")
+        r = conn.execute("SELECT completed_items, current_item FROM "
+                         "skillflow_loop_state WHERE run_id = ?", (run_id,)).fetchone()
+    assert nxt == "process_task"
+    assert "stale_old_task" not in json.loads(r["completed_items"])
+    assert r["current_item"] == "b"
+
+
+def test_loop_progression_credits_on_body_completion(sf_with_workspace):
+    """End-to-end: each item is dispatched once, in order, and completed_items
+    grows only as body cycles complete (progression lives in confirm_step)."""
+    sf = sf_with_workspace
+    run_id = _loop_prepare(sf, [["a", "b", "c"]])
+    count, items = _drive_loop(sf, run_id)
+    assert sf.get_run(run_id)["status"] == "completed"
+    assert count == 3
+    assert items == ["a", "b", "c"]
+
+
+def test_loop_body_nodes_excludes_entry_and_loop(sf_with_workspace):
+    """_loop_body_nodes is the loop body only — excludes the external entry step
+    and the loop node itself (topological, config-agnostic)."""
+    sf = sf_with_workspace
+    _load_and_register(sf, "loop_step.yaml")
+    run_id = sf.create_run("loop_step", project_id="test-loop-bn")
+    sf.start_run(run_id)
+    resolver = sf._get_resolver_for_run(run_id)
+    body = sf._loop_body_nodes(resolver, "task_iterator")
+    assert "process_task" in body        # body node
+    assert "prepare" not in body         # external entry — NOT body
+    assert "task_iterator" not in body   # the loop node itself
+
+
+def test_loop_credit_only_on_body_return_not_entry(sf_with_workspace):
+    """Progression credits current_item only when a BODY step returns to the
+    loop. An external step transitioning INTO the loop (entry / goal-loop
+    re-entry) must NOT credit — else it marks the in-flight item complete and
+    skips it."""
+    import json
+    sf = sf_with_workspace
+    run_id = _loop_prepare(sf, [["alpha", "beta"]])
+    resolver = sf._get_resolver_for_run(run_id)
+    # First dispatch → current_item = "alpha", nothing credited yet.
+    with sf._tx() as conn:
+        run = conn.execute("SELECT * FROM skillflow_runs WHERE id = ?",
+                           (run_id,)).fetchone()
+        sf._resolve_loop(conn, run, resolver, "task_iterator")
+
+    def completed():
+        with sf._tx() as conn:
+            r = conn.execute("SELECT completed_items FROM skillflow_loop_state "
+                             "WHERE run_id = ?", (run_id,)).fetchone()
+            return json.loads(r["completed_items"] or "[]")
+
+    assert completed() == []
+    # External entry step (prepare) resolving into the loop → MUST NOT credit.
+    with sf._tx() as conn:
+        sf._resolve_next_in_tx(conn, run_id, "prepare", {}, resolver)
+    assert completed() == []
+    # Body step (process_task) returning to the loop → credits current_item.
+    with sf._tx() as conn:
+        sf._resolve_next_in_tx(conn, run_id, "process_task", {}, resolver)
+    assert completed() == ["alpha"]
+
+
 def test_loop_body_resolves_per_item_file(sf_with_workspace):
     """Loop body context resolves a per-item file via $current_task — the
     mechanism dpe uses to scope each task_loop iteration to its task card."""