@senpi/runtime 3.0.0-dev.openclaw-upgrade-mai.20260623210452 → 3.0.0-dev.runtime-phase-2.20260623210537

package/dist/scanners/external/scaffold/entrypoint_loader.py

@@ -20,7 +20,7 @@ class ScanEntrypointError(Exception):
 
 
 class ScanSignatureError(Exception):
-    """scan's call shape is incompatible with scan(inputs, ctx)."""
+    """scan's call shape is incompatible with scaffold(params, state[, client])."""
 
 
 def add_path_to_sys_path(path: str) -> None:
@@ -32,22 +32,16 @@ def add_path_to_sys_path(path: str) -> None:
 def import_entrypoint(path: str, entrypoint: str):
     """Put `path` on sys.path, then import `entrypoint` by module name.
 
-    The recipe expresses `entrypoint` as a FILENAME (e.g. `scan.py`, the shape the
-    B1 launcher writes verbatim into the launch config and the §4a entrypoint FS
-    check validates). importlib needs a MODULE name, so a trailing `.py` is
-    stripped here — the only place the filename<->module-name bridge lives.
-
     Raises ScanEntrypointError on any import/syntax/missing-sibling failure,
     chaining the underlying exception.
     """
     add_path_to_sys_path(path)
-    module_name = entrypoint[:-3] if entrypoint.endswith(".py") else entrypoint
     try:
         # Force re-import when the module has been previously imported so that
         # tests can write fresh modules to tmp_path without cache collisions.
-        if module_name in sys.modules:
-            del sys.modules[module_name]
-        return importlib.import_module(module_name)
+        if entrypoint in sys.modules:
+            del sys.modules[entrypoint]
+        return importlib.import_module(entrypoint)
     except Exception as exc:
         raise ScanEntrypointError(
             f"Failed to import entrypoint '{entrypoint}' from '{path}': {exc}"
@@ -73,25 +67,19 @@ def locate_scan(module) -> Callable:
 
 
 def verify_scan_signature(scan: Callable) -> None:
-    """Verify scan's call shape is compatible with the v2 contract scan(inputs, ctx).
-
-    v2 calls scan with EXACTLY two positionals (inputs, ctx). A signature must be
-    callable that way.
+    """Verify scan's call shape is compatible with scan(params, state[, client]).
 
     Accepted shapes:
-        scan(inputs, ctx)                     — 2 required (the canonical shape)
-        scan(inputs, ctx, extra=None)         — 2 required + defaulted extra
-        scan(inputs, ctx, *args)              — variadic absorbs nothing extra here
+        scan(params, state)                   — 2 required
+        scan(params, state, client)           — 3 required
+        scan(params, state, client=None)      — 2 required, 1 optional
+        scan(params, state, *args)            — variadic absorbs client
         scan(*args, **kwargs)                 — fully variadic, accepts anything
 
     Rejected shapes:
         scan()                                — 0 required
-        scan(inputs)                          — 1 required
-        scan(params, state, client)           — 3 required (the OLD v1 client shape)
-        scan(a, b, c, d)                      — >=4 required
-
-    The contract is now EXACTLY two positionals: a 3rd REQUIRED positional cannot
-    be satisfied by scan(inputs, ctx) and is rejected.
+        scan(params)                          — 1 required
+        scan(a, b, c, d)                      — >=4 fixed required
 
     Raises ScanSignatureError naming the found arity on mismatch.
     """
@@ -106,39 +94,57 @@ def verify_scan_signature(scan: Callable) -> None:
     has_var_positional = any(
         p.kind == inspect.Parameter.VAR_POSITIONAL for p in params
     )
+    has_var_keyword = any(
+        p.kind == inspect.Parameter.VAR_KEYWORD for p in params
+    )
 
-    # Required (non-defaulted) fixed positional params.
-    required_fixed = [
+    # A *args/**kwargs-only signature accepts any positional call.
+    if has_var_positional or has_var_keyword:
+        # Check that it actually accepts at least 2 positional args (i.e., no
+        # required positional params ahead of *args that block the call).
+        required_before_var = [
+            p for p in params
+            if p.kind in (
+                inspect.Parameter.POSITIONAL_ONLY,
+                inspect.Parameter.POSITIONAL_OR_KEYWORD,
+            )
+            and p.default is inspect.Parameter.empty
+        ]
+        # If there are >=4 required positionals even WITH *args, reject.
+        if len(required_before_var) >= 4:
+            raise ScanSignatureError(
+                f"scan requires {len(required_before_var)} fixed positional params; "
+                f"expected 2 or 3 (found arity: {len(required_before_var)})."
+            )
+        # Otherwise, variadic accepts our call.
+        return
+
+    # Count fixed positional params (POSITIONAL_ONLY or POSITIONAL_OR_KEYWORD).
+    fixed_positional = [
         p for p in params
         if p.kind in (
             inspect.Parameter.POSITIONAL_ONLY,
             inspect.Parameter.POSITIONAL_OR_KEYWORD,
         )
-        and p.default is inspect.Parameter.empty
     ]
-    n_required = len(required_fixed)
+    required_fixed = [
+        p for p in fixed_positional
+        if p.default is inspect.Parameter.empty
+    ]
 
-    # A *args (or *args/**kwargs) signature accepts the 2-positional call as long
-    # as it has no MORE than 2 required fixed positionals ahead of *args.
-    if has_var_positional:
-        if n_required > 2:
-            raise ScanSignatureError(
-                f"scan requires {n_required} fixed positional params; the v2 "
-                f"contract calls scan(inputs, ctx) — exactly 2. Found arity: {n_required}."
-            )
-        return
+    n_required = len(required_fixed)
+    n_fixed = len(fixed_positional)
 
     if n_required < 2:
         raise ScanSignatureError(
-            f"scan has {n_required} required positional param(s); the v2 contract "
-            f"requires exactly 2 (inputs, ctx). Found arity: {n_required}."
+            f"scan has {n_required} required positional param(s); "
+            f"expected at least 2 (params, state). Found arity: {n_required}."
         )
 
-    if n_required > 2:
+    if n_required >= 4:
         raise ScanSignatureError(
-            f"scan has {n_required} required positional params; the v2 contract "
-            f"calls scan(inputs, ctx) — exactly 2. A 3rd required positional "
-            f"(the old v1 client shape) is no longer accepted. Found arity: {n_required}."
+            f"scan has {n_required} required positional params; "
+            f"expected at most 3 (params, state, client). Found arity: {n_required}."
         )
 
 

package/dist/scanners/external/scaffold/journal.py

@@ -90,19 +90,8 @@ class Journal:
     # ------------------------------------------------------------------
 
     def record_produced(self, signal: dict, *, now_ms: int) -> str:
-        """Write a 'produced' line and enqueue the signal. Returns entry id.
-
-        The entry id IS the wire `signal_id`: the journal stamps `signal_id` onto
-        the persisted/queued signal so the POSTed signal carries the dedup key, and
-        a replay re-uses the SAME id (no fresh id minted on restart). If the signal
-        already carries a `signal_id` (the delivery sink threaded the eid in via the
-        envelope), that id is re-used as the entry id; otherwise one is minted.
-        """
-        existing = signal.get("signal_id")
-        entry_id = existing if isinstance(existing, str) and existing else uuid.uuid4().hex
-        # Stamp the id onto the wire signal so the persisted produced line and the
-        # POSTed body both carry signal_id == entry id.
-        signal["signal_id"] = entry_id
+        """Write a 'produced' line and enqueue the signal. Returns entry id."""
+        entry_id = uuid.uuid4().hex
         asset = signal.get("asset", "")
         valid_until = signal.get("valid_until", 0)
 

package/dist/scanners/external/scaffold/scaffold.py

@@ -1,14 +1,11 @@
-"""Scaffold core loop (v2).
+"""Scaffold core loop.
 
 run_scaffold(...) loads the author's entrypoint, finds and validates scan(),
-builds the ScanContext, then drives the interval loop: time-box per tick, graceful
-stop on SIGTERM/SIGINT, parent-death detection via ppid, transactional state via
-ctx.state, candidates to sink.
-
-`path` is a scaffold concern only — it is put on sys.path before import and never
-passed to scan(). scan() is called as scan(inputs, ctx) — 2-arg, sync, returning a
-plain list[dict]. State mutates ONLY via ctx.state (commit on a clean tick, rollback
-on error/timeout/malformed/failed-persist — transactional discard wins on failure).
+then drives the interval loop: time-box per tick, graceful stop on SIGTERM/SIGINT,
+parent-death detection via ppid, state in/out, candidates to sink.
+
+`path` is a scaffold concern only — it is put on sys.path before import and
+never passed to scan(). scan() is called as scan(params, state, client=None).
 """
 
 import inspect
@@ -17,7 +14,6 @@ import time
 import threading
 from typing import Any, Callable, Optional
 
-from .ctx import ScanContext
 from .entrypoint_loader import (
     ScanEntrypointError,
     ScanSignatureError,
@@ -33,44 +29,40 @@ from .loop_primitives import (
     _interruptible_sleep,
     log_event,
 )
-from .state_manager import StateManager
+from .scaffold_state import read_state, write_state
 
 
-def _build_senpi_mcp() -> Any:
-    """Construct the MCP client when creds are present; else return None.
+def _call_scan(scan: Callable, params: dict, state: Any, client: Any) -> tuple:
+    """Call scan with the right arity.
 
-    Creds come from the launch env (SENPI_API_KEY / SENPI_MCP_URL), injected by
-    the launcher regardless of how the operator supplied them. With neither set,
-    return None so the no-creds path does not crash — the client is loud at FIRST
-    USE (see scaffold.senpi_mcp). Reference the class through the module attribute
-    so a test stub patched onto scaffold.senpi_mcp is honored.
+    Tries scan(params, state, client) first; if that raises TypeError because
+    scan only accepts 2 positional args, falls back to scan(params, state).
+    This lets 2-arg and 3-arg (and variadic) scan functions all work uniformly.
     """
-    api_key = os.environ.get("SENPI_API_KEY") or None
-    mcp_url = os.environ.get("SENPI_MCP_URL") or None
-    if not api_key and not mcp_url:
-        return None
-
-    from . import senpi_mcp as senpi_mcp_mod
-
-    # Read-only-by-default producer MCP boundary: the set of MUTATION tools
-    # producers are permitted to call is owned SOLELY by the scaffold-source
-    # PRODUCER_WRITE_ALLOWLIST constant (EMPTY by default → all mutations
-    # blocked). It is edited by the scaffold maintainer in senpi_mcp.py — it is
-    # NOT operator/env-configurable and NOT reachable by authored producer code.
-    return senpi_mcp_mod.SenpiMcpClient(
-        api_key=api_key,
-        mcp_url=mcp_url,
-        write_allowlist=senpi_mcp_mod.PRODUCER_WRITE_ALLOWLIST,
-    )
-
-
-def _call_scan(scan: Callable, inputs: dict, ctx: Any):
-    """Call scan(inputs, ctx) — the v2 2-arg contract.
+    sig = None
+    try:
+        sig = inspect.signature(scan)
+    except (ValueError, TypeError):
+        pass
+
+    if sig is not None:
+        params_list = list(sig.parameters.values())
+        has_var_positional = any(
+            p.kind == inspect.Parameter.VAR_POSITIONAL for p in params_list
+        )
+        fixed_positional = [
+            p for p in params_list
+            if p.kind in (
+                inspect.Parameter.POSITIONAL_ONLY,
+                inspect.Parameter.POSITIONAL_OR_KEYWORD,
+            )
+        ]
+        # If only 2 fixed positional params (no *args), call 2-arg form.
+        if not has_var_positional and len(fixed_positional) == 2:
+            return scan(params, state)
 
-    There is no `client` and no 3-arg path. scan returns a plain list[dict];
-    validation of that return happens in the tick loop.
-    """
-    return scan(inputs, ctx)
+    # Default: 3-arg call (variadic or 3-param).
+    return scan(params, state, client)
 
 
 def run_scaffold(
@@ -79,17 +71,13 @@ def run_scaffold(
     *,
     interval: float,
     timeout_seconds: Optional[float] = None,
-    inputs: Optional[dict] = None,
+    params: Optional[dict] = None,
     state_path: Optional[str] = None,
-    scanner_name: str,
-    wallet: str,
-    default_signal_validity_seconds: int,
-    state_history_max_count: int = 0,
     sink: Optional[Callable] = None,
     max_ticks: Optional[int] = None,
     install_signal_handlers: bool = True,
 ) -> int:
-    """Load the author's entrypoint and run its scan() on an interval loop (v2).
+    """Load the author's entrypoint and run its scan() on an interval loop.
 
     Args:
         path:        Directory added to sys.path before import. Never passed to scan().
@@ -98,15 +86,9 @@ def run_scaffold(
         timeout_seconds:
                      Per-tick wall-clock budget. Defaults to `interval`. Must be > 0.
                      Enforced via SIGALRM on platforms that support it.
-        inputs:      Tunables dict passed as scan()'s first argument. Default {}.
-        state_path:  Path to the JSON state file. None means no persistence.
-        scanner_name: This scanner's recipe name (read-only ctx metadata).
-        wallet:      Strategy wallet (read-only ctx metadata).
-        default_signal_validity_seconds:
-                     Fallback signal TTL (seconds); threaded to the envelope path.
-        state_history_max_count:
-                     Bound on the persisted state series. 0/unset = history disabled
-                     (ctx.state.append raises).
+        params:      Tunables dict passed as scan()'s first argument. Default {}.
+        state_path:  Path to the JSON state file. Reads on start, written after
+                     each clean tick. None means no persistence.
         sink:        Callable(candidates) invoked after each clean tick. Default no-op.
         max_ticks:   Stop after this many ticks (for tests). None = unbounded.
         install_signal_handlers:
@@ -130,41 +112,14 @@ def run_scaffold(
     if timeout_seconds <= 0:
         raise ValueError(f"timeout_seconds must be > 0; got {timeout_seconds!r}")
 
-    if inputs is None:
-        inputs = {}
+    if params is None:
+        params = {}
 
     # Import and locate scan — any failure raises before tick 1.
     module = import_entrypoint(path, entrypoint)
     scan = locate_scan(module)
     verify_scan_signature(scan)
 
-    # ---------- ctx + state setup ----------
-
-    # The StateManager (B2) is the persisted series. It reads any prior state from
-    # disk on construction. state_history_max_count 0/unset => history disabled
-    # (append raises). It is passed into ctx AS-IS (never wrapped).
-    state = StateManager(state_path, state_history_max_count) if state_path is not None \
-        else StateManager(None, state_history_max_count)
-
-    # ctx.interval_seconds is the integer-seconds cadence (design §2.1). The loop's
-    # `interval` may be a sub-second float in tests; expose the int seconds when it
-    # is whole, else the float as-is.
-    interval_seconds = int(interval) if float(interval).is_integer() else interval
-
-    # B5: fill ctx.senpi_mcp when MCP creds are present (resolved at launch from
-    # SENPI_API_KEY / SENPI_MCP_URL). With no creds the slot stays None and launch
-    # must NOT crash — the client is loud at FIRST USE, not at construction. Import
-    # is deferred so a stub patched onto scaffold.senpi_mcp in tests is honored.
-    senpi_mcp = _build_senpi_mcp()
-
-    ctx = ScanContext(
-        state=state,
-        wallet=wallet,
-        scanner_name=scanner_name,
-        interval_seconds=interval_seconds,
-        senpi_mcp=senpi_mcp,
-    )
-
     # ---------- Lifecycle setup ----------
 
     stop_event = threading.Event()
@@ -173,17 +128,24 @@ def run_scaffold(
 
     start_ppid = os.getppid()
 
+    # Read initial state — corrupt/missing -> None (logged inside read_state).
+    state = read_state(state_path) if state_path is not None else None
+
     log_event(
         "scaffold_started",
         path=path,
         entrypoint=entrypoint,
         interval=interval,
         timeout_seconds=timeout_seconds,
-        scanner_name=scanner_name,
         max_ticks=max_ticks,
     )
 
+    client = None  # placeholder; will be the real data handle in a later unit
     tick_count = 0
+    # True once a state write has failed and we have escalated to /errors;
+    # cleared when a write next succeeds. Throttles the escalation to one
+    # post per failure run (a persistent failure would otherwise post every tick).
+    state_persist_degraded = False
 
     try:
         while not stop_event.is_set():
@@ -197,28 +159,40 @@ def run_scaffold(
             tick_started_at = time.time()
             tick_status = "ok"
             tick_error = None
-            candidates: list = []
+            candidates = []
+            new_state = state  # default: keep current state on error
 
             armed = False
             try:
                 armed = _arm_tick_alarm(timeout_seconds)
                 try:
-                    result = _call_scan(scan, inputs, ctx)
+                    result = _call_scan(scan, params, state, client)
 
-                    # v2 return contract: a PLAIN list[dict]. Anything else is
-                    # malformed (a tuple — the old v1 shape — included).
-                    if not isinstance(result, list):
+                    # Validate the return value: must be a 2-tuple.
+                    if (
+                        not isinstance(result, tuple)
+                        or len(result) != 2
+                    ):
                         tick_status = "malformed"
                         log_event(
                             "scaffold_tick_malformed",
                             tick=tick_count,
-                            reason=(
-                                f"scan() returned {type(result).__name__!r}; expected a "
-                                f"plain list[dict] (the v1 (candidates, state) tuple is gone)"
-                            ),
+                            reason=f"scan() returned {type(result).__name__!r}, expected (candidates, new_state) tuple",
                         )
                     else:
-                        candidates = result
+                        raw_candidates, returned_state = result
+                        # Validate that candidates is iterable.
+                        try:
+                            candidates = list(raw_candidates)
+                        except TypeError:
+                            tick_status = "malformed"
+                            log_event(
+                                "scaffold_tick_malformed",
+                                tick=tick_count,
+                                reason=f"candidates is not iterable (got {type(raw_candidates).__name__!r})",
+                            )
+                        else:
+                            new_state = returned_state
 
                 except _TickTimeout as exc:
                     tick_status = "timeout"
@@ -249,40 +223,48 @@ def run_scaffold(
 
                 duration_ms = int((time.time() - tick_started_at) * 1000)
 
-                # --- Clean tick: commit ctx.state, deliver candidates ---
+                # --- Clean tick: persist (best-effort), advance state, deliver ---
                 if tick_status == "ok":
-                    # Transactional commit. A failed persist RAISES (StateManager
-                    # enforces it) and does NOT advance the committed snapshot — so
-                    # the next tick recomputes from the un-advanced state. On a
-                    # commit failure we roll back and treat the tick as failed
-                    # (discard wins on failed-persist; no advance-on-persist-failure).
-                    committed = True
-                    try:
-                        ctx.state.commit()
-                    except Exception as commit_exc:  # noqa: BLE001
-                        committed = False
-                        ctx.state.rollback()
-                        log_event(
-                            "scaffold_state_persist_failed",
-                            tick=tick_count,
-                            error_type=type(commit_exc).__name__,
-                            error=str(commit_exc),
-                        )
-                        if sink is not None and hasattr(sink, "post_error"):
-                            _post_error_safe(
-                                sink,
-                                {
-                                    "type": "state_persist_failed",
-                                    "tick": tick_count,
-                                    "message": (
-                                        "scanner state could not be persisted; "
-                                        "tick discarded, state not advanced"
-                                    ),
-                                },
-                                tick_count,
-                            )
-
-                    if committed and sink is not None:
+                    # Disk persistence is best-effort: advance the in-memory state
+                    # regardless of the write result, so the next tick never
+                    # recomputes from stale state (which could re-deliver the same
+                    # signal). But a persist failure is almost always persistent
+                    # (unserialisable state, read-only dir, full disk), and the
+                    # un-persisted ticks are LOST on the next restart — silently
+                    # degrading any scanner that decides on accumulated history.
+                    # So escalate it like a tick error: post to /errors once on the
+                    # first failure (throttled while it keeps failing) and clear
+                    # when a write next succeeds.
+                    if state_path is not None:
+                        if write_state(state_path, new_state):
+                            if state_persist_degraded:
+                                state_persist_degraded = False
+                                log_event("scaffold_state_persist_recovered", tick=tick_count)
+                        else:
+                            log_event("scaffold_state_persist_failed", tick=tick_count)
+                            if not state_persist_degraded:
+                                state_persist_degraded = True
+                                if sink is not None and hasattr(sink, "post_error"):
+                                    try:
+                                        sink.post_error({
+                                            "type": "state_persist_failed",
+                                            "tick": tick_count,
+                                            "message": (
+                                                "scanner state could not be persisted; "
+                                                "accumulated history will be lost on restart"
+                                            ),
+                                        })
+                                    except Exception as perr:  # noqa: BLE001
+                                        log_event(
+                                            "scaffold_post_error_failed",
+                                            tick=tick_count,
+                                            error_type=type(perr).__name__,
+                                            error=str(perr),
+                                        )
+                    state = new_state
+
+                    # Hand candidates to the delivery sink.
+                    if sink is not None:
                         try:
                             sink(candidates)
                         except Exception as sink_exc:  # noqa: BLE001
@@ -293,14 +275,18 @@ def run_scaffold(
                                 error=str(sink_exc),
                             )
                 else:
-                    # Non-ok tick (error / timeout / malformed): roll back the
-                    # working buffer (discard the tick's mutations — state not
-                    # advanced) and report to /errors via the sink, when supported.
-                    ctx.state.rollback()
+                    # Non-ok tick (error / timeout / malformed): report it to the
+                    # runtime's errors endpoint via the sink, when supported.
                     if sink is not None and hasattr(sink, "post_error"):
-                        _post_error_safe(
-                            sink, tick_error or {"type": tick_status}, tick_count
-                        )
+                        try:
+                            sink.post_error(tick_error or {"type": tick_status})
+                        except Exception as perr:  # noqa: BLE001
+                            log_event(
+                                "scaffold_post_error_failed",
+                                tick=tick_count,
+                                error_type=type(perr).__name__,
+                                error=str(perr),
+                            )
 
                 log_event(
                     "scaffold_tick_finished",
@@ -311,15 +297,11 @@ def run_scaffold(
                 )
 
             except _TickTimeout as late_exc:
-                # A SIGALRM queued by the OS, delivered after the inner try/except
-                # exited (e.g. during commit, sink, or log_event). Absorb it: the
-                # tick already did its work; disarm, roll back any uncommitted
-                # mutations, log the late arrival, and let the loop continue.
+                # A SIGALRM queued by the OS was delivered after the inner
+                # try/except exited (e.g. during write_state, sink, or log_event).
+                # Absorb it: the tick already did its work; disarm just in case,
+                # log the late arrival, and let the loop continue.
                 _disarm_tick_alarm()
-                try:
-                    ctx.state.rollback()
-                except Exception:  # noqa: BLE001
-                    pass
                 log_event(
                     "scaffold_tick_timeout_late",
                     tick=tick_count,
@@ -346,16 +328,3 @@ def run_scaffold(
         log_event("scaffold_stopping", tick_count=tick_count)
 
     return tick_count
-
-
-def _post_error_safe(sink: Any, error: dict, tick_count: int) -> None:
-    """Call sink.post_error(error), swallowing/logging any failure."""
-    try:
-        sink.post_error(error)
-    except Exception as perr:  # noqa: BLE001
-        log_event(
-            "scaffold_post_error_failed",
-            tick=tick_count,
-            error_type=type(perr).__name__,
-            error=str(perr),
-        )