simplicio-loop 1.0.2__py3-none-any.whl

simplicio_loop/__init__.py

@@ -0,0 +1,8 @@
+"""simplicio-loop — The Universal Looping AI Orchestrator.
+
+A runtime-agnostic super-plugin (6 skills + loop/token hooks) that drains any
+queue of work end-to-end on any LLM/runtime. This package ships the skills and
+hooks and installs them into a runtime's skills location.
+"""
+
+__version__ = "1.0.2"

simplicio_loop/_bundle/hooks/hooks.claude.json

@@ -0,0 +1,20 @@
+{
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          { "type": "command", "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/hooks/loop_stop.py\"" },
+          { "type": "command", "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/hooks/learn_stop.py\"" }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          { "type": "command", "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/hooks/orient_rewrite.py\"" }
+        ]
+      }
+    ]
+  }
+}

simplicio_loop/_bundle/hooks/hooks.json

@@ -0,0 +1,12 @@
+{
+  "version": 1,
+  "hooks": {
+    "afterAgentResponse": [
+      { "command": "python3 ./hooks/loop_capture.py" }
+    ],
+    "stop": [
+      { "command": "python3 ./hooks/loop_stop.py", "loop_limit": null },
+      { "command": "python3 ./hooks/learn_stop.py" }
+    ]
+  }
+}

simplicio_loop/_bundle/hooks/learn_stop.py

@@ -0,0 +1,38 @@
+#!/usr/bin/env python3
+"""simplicio-learn — session-end trigger (Stop / SubagentStop, fail-open).
+
+Drops a lightweight marker so the next simplicio-tasks tick (or the human) runs the
+`simplicio-learn` retrospective on the just-finished run. It does NOT itself mine the
+transcript (that's the skill's job, where the model can judge signal) — it only signals
+"there is a finished run worth learning from", with the transcript path if the host gave one.
+
+Fail-open and silent: never blocks stopping, never errors out loud.
+"""
+import json
+import os
+import sys
+import time
+
+LEARN_DIR = os.path.join(".orchestrator", "learn")
+QUEUE = os.path.join(LEARN_DIR, "pending.jsonl")
+
+
+def main():
+    try:
+        raw = sys.stdin.read()
+        data = json.loads(raw) if raw.strip() else {}
+        os.makedirs(LEARN_DIR, exist_ok=True)
+        rec = {
+            "at": int(time.time()),
+            "transcript": data.get("transcript_path") or data.get("transcriptPath"),
+            "session": data.get("session_id") or data.get("sessionId"),
+        }
+        with open(QUEUE, "a", encoding="utf-8") as f:
+            f.write(json.dumps(rec) + "\n")
+    except Exception:
+        pass
+    sys.exit(0)  # never block the stop
+
+
+if __name__ == "__main__":
+    main()

simplicio_loop/_bundle/hooks/loop_capture.py

@@ -0,0 +1,67 @@
+#!/usr/bin/env python3
+"""simplicio-loop — capture hook (Cursor `afterAgentResponse`).
+
+Runs after every agent turn. Detects an evidence-backed completion-promise and
+raises the `done` flag for the stop hook to act on. Detection and termination are
+split on purpose (the ralph-loop two-hook pattern): this script NEVER stops the
+loop, it only raises the flag. Fire-and-forget, always exit 0.
+
+On Claude Code (which has no separate post-response hook) this script is unused —
+`loop_stop.py` folds capture in by reading the transcript. Harmless if wired anyway.
+"""
+import json
+import os
+import re
+import sys
+
+LOOP_DIR = os.path.join(".orchestrator", "loop")
+SCRATCHPAD = os.path.join(LOOP_DIR, "scratchpad.md")
+DONE_FLAG = os.path.join(LOOP_DIR, "done")
+LAST_RESP = os.path.join(LOOP_DIR, "last_response.txt")
+
+PROMISE_RE = re.compile(r"<promise>\s*(.*?)\s*</promise>", re.IGNORECASE | re.DOTALL)
+EVIDENCE_RE = re.compile(
+    r"(https?://\S+/pull/\d+)|(\b(pass|passed|passing|green|ok)\b)|([\w./-]+:\d+)|([✓✅])",
+    re.IGNORECASE,
+)
+
+
+def main():
+    try:
+        raw = sys.stdin.read()
+        data = json.loads(raw) if raw.strip() else {}
+        resp = data.get("text", "") or ""
+        if not resp:
+            sys.exit(0)
+        # Stash the response so a unified stop hook can read it cross-runtime.
+        try:
+            os.makedirs(LOOP_DIR, exist_ok=True)
+            with open(LAST_RESP, "w", encoding="utf-8") as f:
+                f.write(resp)
+        except OSError:
+            pass
+        if not os.path.exists(SCRATCHPAD):
+            sys.exit(0)
+        with open(SCRATCHPAD, encoding="utf-8") as f:
+            content = f.read()
+        m_prom = re.search(r"^completion_promise:\s*(.*)$", content, re.M)
+        if not m_prom:
+            sys.exit(0)
+        promise = m_prom.group(1).strip().strip('"')
+        if promise in ("", "null"):
+            sys.exit(0)
+        evidence_required = "evidence_required: false" not in content.lower()
+        m = PROMISE_RE.search(resp)
+        if m and m.group(1).strip() == promise:
+            if (not evidence_required) or EVIDENCE_RE.search(resp):
+                try:
+                    open(DONE_FLAG, "w").close()  # raise the flag; stop hook acts
+                except OSError:
+                    pass
+    except Exception:
+        pass
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

simplicio_loop/_bundle/hooks/loop_stop.py

@@ -0,0 +1,205 @@
+#!/usr/bin/env python3
+"""simplicio-loop — stop hook (cross-runtime, cross-platform).
+
+Fires when an agent turn ends. Decides whether to RE-FEED the goal (continue the
+Ralph loop) or let the agent STOP. Works under Claude Code (Stop hook) and Cursor
+(stop hook); detects the runtime from env and emits the matching control object.
+
+SAFETY: fail-open. On ANY error, ambiguity, or missing state, ALLOW STOP — a buggy
+hook must never trap the agent in an endless loop. The real guards are the
+`max_iterations` cap and the $ budget kill-switch, never this script's cleverness.
+
+State (single source of truth): .orchestrator/loop/scratchpad.md  (+ sibling `done` flag)
+Reads stdin JSON from the host (Claude: {transcript_path,...}; Cursor: {text,...}).
+"""
+import json
+import os
+import re
+import sys
+
+LOOP_DIR = os.path.join(".orchestrator", "loop")
+SCRATCHPAD = os.path.join(LOOP_DIR, "scratchpad.md")
+DONE_FLAG = os.path.join(LOOP_DIR, "done")
+LAST_RESP = os.path.join(LOOP_DIR, "last_response.txt")
+STOP_SIGNAL = os.path.join(".orchestrator", "STOP")
+BUDGET = os.path.join(".orchestrator", "loop-budget.json")
+
+EVIDENCE_RE = re.compile(
+    r"(https?://\S+/pull/\d+)"          # a PR URL
+    r"|(\b(pass|passed|passing|green|ok)\b)"  # a gate verdict
+    r"|([\w./-]+:\d+)"                   # a file:line receipt
+    r"|([✓✅])",
+    re.IGNORECASE,
+)
+PROMISE_RE = re.compile(r"<promise>\s*(.*?)\s*</promise>", re.IGNORECASE | re.DOTALL)
+
+
+def allow_stop():
+    """Emit nothing actionable → the agent is allowed to stop. Always exit 0."""
+    sys.exit(0)
+
+
+def cleanup_and_stop():
+    for p in (SCRATCHPAD, DONE_FLAG, LAST_RESP):
+        try:
+            if os.path.exists(p):
+                os.remove(p)
+        except OSError:
+            pass
+    allow_stop()
+
+
+def read_stdin_json():
+    try:
+        raw = sys.stdin.read()
+        return json.loads(raw) if raw.strip() else {}
+    except Exception:
+        return {}
+
+
+def parse_frontmatter(text):
+    """Return (meta dict, body str) or (None, None) on corruption."""
+    if not text.startswith("---"):
+        return None, None
+    parts = text.split("---", 2)
+    if len(parts) < 3:
+        return None, None
+    meta = {}
+    for line in parts[1].splitlines():
+        if ":" in line:
+            k, _, v = line.partition(":")
+            meta[k.strip()] = v.strip().strip('"')
+    return meta, parts[2].strip()
+
+
+def last_assistant_text(stdin):
+    # Cursor passes the response text inline.
+    if isinstance(stdin.get("text"), str):
+        return stdin["text"]
+    # Cursor capture hook may have stashed it.
+    if os.path.exists(LAST_RESP):
+        try:
+            with open(LAST_RESP, encoding="utf-8") as f:
+                return f.read()
+        except OSError:
+            pass
+    # Claude passes a transcript path (JSONL); read the last assistant message.
+    tp = stdin.get("transcript_path")
+    if tp and os.path.exists(tp):
+        try:
+            txt = ""
+            with open(tp, encoding="utf-8") as f:
+                for line in f:
+                    try:
+                        ev = json.loads(line)
+                    except Exception:
+                        continue
+                    if ev.get("role") == "assistant" or ev.get("type") == "assistant":
+                        msg = ev.get("message", ev)
+                        content = msg.get("content", "")
+                        if isinstance(content, list):
+                            content = " ".join(
+                                c.get("text", "") for c in content if isinstance(c, dict)
+                            )
+                        txt = content or txt
+            return txt
+        except OSError:
+            return ""
+    return ""
+
+
+def budget_halted():
+    try:
+        if not os.path.exists(BUDGET):
+            return False
+        with open(BUDGET, encoding="utf-8") as f:
+            b = json.load(f)
+        if str(b.get("state", "")).lower() == "halted":
+            return True
+        ceiling = float(b.get("daily_usd_ceiling", 0) or 0)
+        spent = float(b.get("spent_usd_today", 0) or 0)
+        return ceiling > 0 and spent >= ceiling
+    except Exception:
+        return False  # fail-open: budget unreadable ≠ trap
+
+
+def emit_refeed(followup):
+    """Emit the re-feed in BOTH schemas; each runtime reads its own key."""
+    out = {
+        "followup_message": followup,            # Cursor
+        "decision": "block",                      # Claude Code Stop hook
+        "reason": followup,
+    }
+    sys.stdout.write(json.dumps(out))
+    sys.exit(0)
+
+
+def main():
+    try:
+        # Explicit STOP signal beats everything.
+        if os.path.exists(STOP_SIGNAL):
+            cleanup_and_stop()
+        # (1) No active loop.
+        if not os.path.exists(SCRATCHPAD):
+            allow_stop()
+        with open(SCRATCHPAD, encoding="utf-8") as f:
+            content = f.read()
+        meta, body = parse_frontmatter(content)
+        # (2) Corrupt state.
+        if meta is None:
+            cleanup_and_stop()
+        try:
+            iteration = int(meta.get("iteration", "1"))
+            max_iter = int(meta.get("max_iterations", "0"))
+        except ValueError:
+            cleanup_and_stop()
+        promise = meta.get("completion_promise", "null")
+        promise = None if promise in (None, "null", "") else promise
+        evidence_required = str(meta.get("evidence_required", "true")).lower() != "false"
+
+        stdin = read_stdin_json()
+        resp = last_assistant_text(stdin)
+
+        # Completion detection (capture folded in for single-hook runtimes like Claude).
+        if promise and resp:
+            m = PROMISE_RE.search(resp)
+            if m and m.group(1).strip() == promise.strip():
+                has_evidence = bool(EVIDENCE_RE.search(resp))
+                if (not evidence_required) or has_evidence:
+                    cleanup_and_stop()  # (3) promise fulfilled → stop
+                # promise without evidence → ignore, keep looping
+        # (3') Cursor capture may have raised the flag.
+        if os.path.exists(DONE_FLAG):
+            cleanup_and_stop()
+        # (4) Iteration cap.
+        if max_iter > 0 and iteration >= max_iter:
+            cleanup_and_stop()
+        # (5) Budget halted.
+        if budget_halted():
+            cleanup_and_stop()
+        # (6) Continue: bump iteration in place, re-feed the goal body.
+        nxt = iteration + 1
+        new_content = re.sub(
+            r"^iteration:\s*\d+", "iteration: %d" % nxt, content, count=1, flags=re.M
+        )
+        try:
+            tmp = SCRATCHPAD + ".tmp"
+            with open(tmp, "w", encoding="utf-8") as f:
+                f.write(new_content)
+            os.replace(tmp, SCRATCHPAD)
+        except OSError:
+            allow_stop()  # can't persist progress → don't risk an unbounded loop
+        promise_hint = (
+            " To finish: output <promise>%s</promise> ONLY when genuinely true AND "
+            "backed by a passing gate." % promise
+            if promise
+            else ""
+        )
+        header = "[simplicio-loop iteration %d.%s]" % (nxt, promise_hint)
+        emit_refeed(header + "\n\n" + (body or ""))
+    except Exception:
+        allow_stop()  # fail-open, always
+
+
+if __name__ == "__main__":
+    main()

simplicio_loop/_bundle/hooks/orient_clamp.py

@@ -0,0 +1,167 @@
+#!/usr/bin/env python3
+"""simplicio-orient — command clamp wrapper (rtk core, portable).
+
+Run a dev command and return its output REDUCED before it reaches the model context:
+  success-collapse · dedup-with-counts · signal-tiered caps · tee-cache on failure.
+
+Usage:
+    python3 hooks/orient_clamp.py -- <command> [args...]
+    python3 hooks/orient_clamp.py --json -- <command> [args...]   # machine summary
+
+Works on Windows/macOS/Linux (pure Python, no shell-specific syntax). Safe and
+fail-open: on ANY internal error it prints the raw output and propagates the REAL
+exit code — it can never turn "task works" into "task dead".
+
+Config (optional): .orchestrator/orient.toml
+    [tee]   mode = "failures" | "always" | "never"   (default failures)
+    [hooks] exclude_commands = ["curl", "wget", "playwright", "ssh", "vim", "less"]
+Excluded commands run RAW (streaming/interactive/binary must not be filtered).
+"""
+import os
+import re
+import subprocess
+import sys
+import time
+
+try:  # Windows consoles default to cp1252 — force UTF-8 so arbitrary output never crashes.
+    sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+except Exception:
+    pass
+
+CAP_ERRORS = 20
+CAP_WARNINGS = 10
+CAP_LIST = 20
+TEE_DIR = os.path.join(".orchestrator", "tee")
+CONFIG = os.path.join(".orchestrator", "orient.toml")
+DEFAULT_EXCLUDES = ["curl", "wget", "playwright", "ssh", "vim", "less", "top", "htop"]
+
+ERR_RE = re.compile(r"\b(error|fail(ed|ure)?|panic|exception|fatal|traceback)\b", re.I)
+WARN_RE = re.compile(r"\bwarn(ing)?\b", re.I)
+CLEAN_RE = re.compile(
+    r"^(ok|done|success|up.to.date|no changes|nothing to commit|pass(ed|ing)?)", re.I
+)
+
+
+def load_config():
+    mode, excludes = "failures", list(DEFAULT_EXCLUDES)
+    try:
+        if os.path.exists(CONFIG):
+            txt = open(CONFIG, encoding="utf-8").read()
+            m = re.search(r'mode\s*=\s*"(\w+)"', txt)
+            if m:
+                mode = m.group(1)
+            m = re.search(r"exclude_commands\s*=\s*\[(.*?)\]", txt, re.S)
+            if m:
+                excludes = re.findall(r'"([^"]+)"', m.group(1)) or excludes
+    except Exception:
+        pass
+    return mode, excludes
+
+
+def is_excluded(cmd, excludes):
+    joined = " ".join(cmd).lower()
+    return any(joined.startswith(x.lower()) or (" " + x.lower() + " ") in (" " + joined + " ")
+               for x in excludes)
+
+
+def tee_write(cmd, raw):
+    try:
+        os.makedirs(TEE_DIR, exist_ok=True)
+        slug = re.sub(r"[^a-z0-9]+", "_", " ".join(cmd).lower())[:40].strip("_")
+        path = os.path.join(TEE_DIR, "%d_%s.log" % (int(time.time()), slug or "cmd"))
+        with open(path, "w", encoding="utf-8", errors="replace") as f:
+            f.write(raw)
+        return path
+    except Exception:
+        return None
+
+
+def dedup_counts(lines):
+    out, prev, n = [], None, 0
+    for ln in lines:
+        if ln == prev:
+            n += 1
+        else:
+            if prev is not None:
+                out.append(prev if n == 1 else "%s  x%d" % (prev, n))
+            prev, n = ln, 1
+    if prev is not None:
+        out.append(prev if n == 1 else "%s  ×%d" % (prev, n))
+    return out
+
+
+def clamp(raw, exit_code):
+    lines = raw.splitlines()
+    err = [l for l in lines if ERR_RE.search(l)]
+    warn = [l for l in lines if WARN_RE.search(l) and l not in err]
+    # success-collapse: clean exit, no error/warning → one line
+    if exit_code == 0 and not err and not warn:
+        first = next((l for l in lines if l.strip()), "")
+        if not lines or CLEAN_RE.search(first.strip()) or len(lines) <= 1:
+            return (first.strip() or "ok"), False
+        kept = dedup_counts([l for l in lines if l.strip()])[:CAP_LIST]
+        clipped = len(kept) < len([l for l in lines if l.strip()])
+        return "\n".join(kept), clipped
+    # has errors/warnings → keep signal, dedup
+    body = dedup_counts(err)[:CAP_ERRORS] + dedup_counts(warn)[:CAP_WARNINGS]
+    clipped = len(err) > CAP_ERRORS or len(warn) > CAP_WARNINGS
+    if not body:  # underflow-safe: fall back to a tail of raw
+        body = [l for l in lines if l.strip()][-CAP_ERRORS:]
+        clipped = clipped or len(lines) > CAP_ERRORS
+    return "\n".join(body), clipped
+
+
+def main():
+    argv = sys.argv[1:]
+    as_json = False
+    if argv and argv[0] == "--json":
+        as_json, argv = True, argv[1:]
+    if not argv or argv[0] != "--" or len(argv) < 2:
+        sys.stderr.write("usage: orient_clamp.py [--json] -- <command> [args...]\n")
+        sys.exit(2)
+    cmd = argv[1:]
+    mode, excludes = load_config()
+
+    # Excluded → run raw, stream through unchanged.
+    if is_excluded(cmd, excludes):
+        try:
+            return sys.exit(subprocess.call(cmd))
+        except Exception as e:
+            sys.stderr.write("orient_clamp passthrough error: %s\n" % e)
+            sys.exit(1)
+
+    try:
+        proc = subprocess.run(cmd, capture_output=True, text=True, errors="replace")
+        raw = (proc.stdout or "") + (proc.stderr or "")
+        code = proc.returncode
+    except FileNotFoundError:
+        sys.stderr.write("orient_clamp: command not found: %s\n" % cmd[0])
+        sys.exit(127)
+    except Exception:
+        # fail-open: re-run inheriting stdio so the user still gets the real result
+        try:
+            sys.exit(subprocess.call(cmd))
+        except Exception:
+            sys.exit(1)
+
+    reduced, clipped = clamp(raw, code)
+    tee_path = None
+    if mode == "always" or (mode == "failures" and (code != 0 or (clipped and code != 0))):
+        tee_path = tee_write(cmd, raw)
+
+    if as_json:
+        import json
+        print(json.dumps({
+            "exit": code, "reduced": reduced, "tee": tee_path,
+            "raw_chars": len(raw), "reduced_chars": len(reduced),
+        }))
+    else:
+        print(reduced)
+        if tee_path:
+            print("[full output: %s]" % tee_path)
+    sys.exit(code)  # propagate the REAL exit code
+
+
+if __name__ == "__main__":
+    main()

simplicio_loop/_bundle/hooks/orient_rewrite.py

@@ -0,0 +1,96 @@
+#!/usr/bin/env python3
+"""simplicio-orient — auto-rewrite hook (PreToolUse, best-effort, fail-open).
+
+Transparently routes a bare heavy READ-ONLY command through `orient_clamp.py` so its
+output is reduced before it reaches context — rtk's `init -g` idea. Guarantees adoption
+across the main agent AND subagents at zero token overhead, where the host supports
+PreToolUse input rewriting (newer Claude Code; Cursor).
+
+CONSERVATIVE BY DESIGN (safety > savings):
+  • Only wraps a small allowlist of read-only commands (git status/log/diff/show, ls,
+    rg, cat/type, and known test/build runners).
+  • NEVER touches writes, excluded commands, or compound commands (&&, ||, |, ;, >, <,
+    backticks, $()) — those run unchanged.
+  • Fail-open: on ANY error or unknown protocol, allow the command unchanged. If the host
+    ignores the rewrite, the command simply runs raw — never broken.
+
+Disabled unless wired explicitly (see hooks/README.md). Honest note: where a runtime
+cannot rewrite tool input, this no-ops; use `orient_clamp.py` as a manual wrapper instead.
+"""
+import json
+import os
+import re
+import sys
+
+CLAMP = os.path.join(os.path.dirname(os.path.abspath(__file__)), "orient_clamp.py")
+CONFIG = os.path.join(".orchestrator", "orient.toml")
+DEFAULT_EXCLUDES = ["curl", "wget", "playwright", "ssh", "vim", "less", "top", "htop"]
+
+# read-only, output-heavy commands worth clamping (prefix match on the first token(s))
+ALLOW = [
+    "git status", "git log", "git diff", "git show", "git branch",
+    "ls", "ll", "dir", "rg ", "grep ", "cat ", "type ", "tree",
+    "cargo check", "cargo test", "cargo clippy", "cargo build",
+    "npm test", "npm run", "pnpm test", "yarn test", "jest", "vitest",
+    "go test", "go build", "go vet", "pytest", "python -m pytest",
+    "mvn ", "gradle ", "tsc", "eslint", "ruff", "golangci-lint",
+]
+UNSAFE = re.compile(r"[|&;><`]|\$\(|>>|<<")  # compound / redirect / substitution
+
+
+def allow_unchanged():
+    # Emit a permissive decision that does not modify anything; host runs the command raw.
+    print(json.dumps({
+        "hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "allow"}
+    }))
+    sys.exit(0)
+
+
+def load_excludes():
+    excludes = list(DEFAULT_EXCLUDES)
+    try:
+        if os.path.exists(CONFIG):
+            m = re.search(r"exclude_commands\s*=\s*\[(.*?)\]",
+                          open(CONFIG, encoding="utf-8").read(), re.S)
+            if m:
+                excludes = re.findall(r'"([^"]+)"', m.group(1)) or excludes
+    except Exception:
+        pass
+    return excludes
+
+
+def main():
+    try:
+        raw = sys.stdin.read()
+        data = json.loads(raw) if raw.strip() else {}
+        ti = data.get("tool_input", data.get("toolInput", {})) or {}
+        cmd = (ti.get("command") or ti.get("cmd") or "").strip()
+        if not cmd:
+            allow_unchanged()
+        low = cmd.lower()
+        # already wrapped, unsafe-shape, or excluded → leave raw
+        if "orient_clamp" in low or UNSAFE.search(cmd):
+            allow_unchanged()
+        if any(low.startswith(x.lower()) or (" " + x.lower()) in (" " + low)
+               for x in load_excludes()):
+            allow_unchanged()
+        if not any(low.startswith(a.lower()) for a in ALLOW):
+            allow_unchanged()
+        # eligible → rewrite to route through the clamp wrapper
+        new_cmd = 'python3 "%s" -- %s' % (CLAMP, cmd)
+        out = {
+            "hookSpecificOutput": {
+                "hookEventName": "PreToolUse",
+                "permissionDecision": "allow",
+                "updatedInput": {"command": new_cmd},   # newer Claude Code
+            },
+            "updatedInput": {"command": new_cmd},        # alt schema; ignored if unknown
+        }
+        print(json.dumps(out))
+        sys.exit(0)
+    except Exception:
+        allow_unchanged()  # fail-open, always
+
+
+if __name__ == "__main__":
+    main()