superqode 2.5.4__tar.gz → 2.5.6__tar.gz

{superqode-2.5.4 → superqode-2.5.6}/CHANGELOG.md

@@ -7,6 +7,68 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.5.6] - 2026-10-04
+
+### Added
+
+- Optional A2A delegation inside native RLM's existing Python tool, with durable
+  task handles, bounded context and results, restart reconciliation and explicit
+  hosted credit admission. Routes and paid fallback remain off by default.
+- Open **Optional A2A** in the Harness Hub or `:rlm a2a` to configure peers,
+  key environment references and credit limits. Save project profiles or branch
+  into a new session; inspect the active worker policy, remote tasks and usage.
+- Choose RLM from `:connect` to see host, Docker and Monty execution choices
+  alongside optional A2A setup before continuing the model connection flow.
+- Retained agent inboxes and explicit child continuations, root-wide semantic
+  subcall admission, and Monty resource limits and persistent checkpoints.
+- Hosted specialist entitlements, durable customer credit reservations and
+  unverified remote evidence receipts in the existing WorkOrder acceptance flow.
+
+### Notes
+
+- Paid hosted execution remains disabled on the public Cloud Run catalogue.
+  The hosted specialist implementation supports a single durable host pilot;
+  multi-instance Cloud Run execution requires a shared durable backend.
+- Hosted service setup requires a signing secret, customer credits, durable
+  task and credit stores, and an isolated read-only specialist harness.
+- Native RLM and WorkOrders retain their existing execution and acceptance paths.
+  Real workload cost and coding-quality measurements remain outstanding.
+
+## [2.5.5] - 2026-10-04
+
+### Added
+
+- Open `:work view ID` for live task dependencies, assigned predecessor evidence,
+  recovery outcomes, acceptance output and candidate review in the TUI.
+- Run existing WorkOrder actions without leaving the inspector. An explicit
+  Interrupt control stops its own worker process; stale leases and unknown
+  outcomes still require recovery and, when necessary, reconciliation.
+- Open `:context evidence` to inspect native Core/hosted PiPy decisions,
+  proposed excerpts, bounded originals and persisted cache reuse after a new step.
+- Add a small real coding WorkOrder demo with an investigator dependency and
+  deterministic acceptance test. Setup is offline; Execute uses the chosen
+  provider. Recovery requires the explicit `--recovery` flag.
+
+### Hardened
+
+- Record reuse admissions only after invocation identity, current ownership,
+  configuration and workspace checks. Recovery views exclude private outcomes.
+- Require a complete, integrity-checked candidate preview and a human reason
+  for TUI approval. Atomically check both candidate identity and digest to reject
+  approval races, including replacement candidates with identical patch bytes.
+- Recheck current permissions on each evidence page. Bound previews, preserve
+  keyboard focus and draft text, and support 80-column terminal layouts.
+- Gate releases on mounted TUI workflows and real PiPy process interruption,
+  restart and committed-call reuse tests with deterministic model responses.
+
+### Notes
+
+- Recovery, evidence reuse and context/Jev selection remain opt-in. Context
+  selection defaults to `off`; shadow mode preserves baseline output. No model
+  routing, price optimization or external harness context-parity claim is added.
+- Live Pi/Jev coding-quality comparisons and net-benefit measurements remain
+  outstanding. These changes expose and harden the existing execution contracts.
+
 ## [2.5.4] - 2026-10-03
 
 ### Fixed

{superqode-2.5.4 → superqode-2.5.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: superqode
-Version: 2.5.4
+Version: 2.5.6
 Summary: The harness layer for coding agents
 Author-email: Shashi Jagtap <info@super-agentic.ai>
 Maintainer-email: Shashi Jagtap <info@super-agentic.ai>

superqode-2.5.6/examples/harnesses/rlm-a2a.yaml

@@ -0,0 +1,62 @@
+version: 1
+name: rlm-optional-a2a
+description: Bounded Monty context analysis with explicit optional remote review.
+flavor: coding
+runtime:
+  backend: rlm
+  config:
+    resident_root: true
+    durable_children: false
+    sandbox: monty
+    allow_network: false
+    allow_write: false
+    max_depth: 2
+    max_children: 4
+    max_parallel: 2
+    subcall_max_calls: 8
+    subcall_max_batch: 4
+    subcall_max_concurrency: 2
+    subcall_max_prompt_chars: 32000
+    subcall_max_response_chars: 4000
+    monty_max_workers: 2
+    monty_memory_bytes: 67108864
+    monty_recursion_depth: 128
+    monty_suspensions: 128
+    python_timeout: 60
+    max_output_chars: 20000
+    max_checkpoint_bytes: 16777216
+    a2a:
+      # Enable only after choosing and authorizing this peer.
+      enabled: false
+      hosted_enabled: false
+      max_hosted_credits: 0
+      max_tasks: 4
+      max_parallel: 1
+      max_payload_bytes: 128000
+      max_result_bytes: 1000000
+      deadline_seconds: 300
+      peers:
+        - name: reviewer
+          url: http://127.0.0.1:8000
+          description: Review selected evidence and cite source locations.
+          skill: superqode-harness
+          # For an authenticated peer, resolve its key only on the host:
+          # credential_env: REVIEWER_A2A_KEY
+model_policy:
+  profile: rlm
+execution_policy:
+  sandbox: monty
+  approval_profile: none
+  allow_read: true
+  allow_write: false
+  allow_shell: false
+  allow_network: false
+agents:
+  - id: rlm
+    role: recursive-analysis
+    tools: [python]
+metadata:
+  example: native-rlm-optional-a2a
+  model_tool_count: 1
+  resident_root: true
+  read_only: true

superqode-2.5.6/examples/rlm-a2a-eval/README.md

@@ -0,0 +1,35 @@
+# RLM/A2A comparison pack
+
+`tasks.json` defines three small tasks, expected evidence, comparison conditions,
+and required measurements. Run with the same root model, revision, task inputs,
+budgets and acceptance gates across conditions. For the long-log task, repeat
+`source` as directed and append `selected`. For the migration task, use the stated
+local gate to reject the broken implementation. Monty must hand verification to
+a configured executor or report that verification is unavailable.
+
+Start with the offline contract/failure suite; it invokes no paid models:
+
+```bash
+.venv/bin/python -m pytest tests/rlm/test_rlm_a2a_delegation.py \
+  tests/test_a2a_hosted_credits.py tests/rlm/test_rlm_monty_kernel.py \
+  tests/rlm/test_rlm_sandboxed_kernel.py -q
+```
+
+Those checks exercise actual host and Monty kernels, Docker's portable protocol
+surface, independent A2A wire fixtures, actual inbound SDK requests, concurrent
+admission, lost acknowledgments, restart, timeouts, retained inboxes and quotas.
+Real Docker boundary checks are in `tests/rlm/test_rlm_docker_kernel.py` and skip
+when no daemon is available. They are a required pre-release check on a Docker host.
+
+Model evaluations require configured user-owned routes and explicit allowances.
+Collect the listed metrics for each task/condition/profile; retain the raw events
+and exported bundle digests. Separate cold and warm workers. Repeat model trials
+and report variation, failed gates and unknown spend, including unsuccessful
+runs. Compare local and loopback A2A with the exact same specialist first, so
+specialist tools/data are not mistaken for a benefit from transport itself.
+
+The deterministic tests establish correctness and bounded context export. They
+are not evidence of answer-quality improvements, production cost savings or a
+new default profile. Automatic routing remains disabled until workload results
+justify it. Pi Durable findings remain exploratory and do not replace RLM or
+WorkOrders.

superqode-2.5.6/examples/workorders/tui_demo.py

@@ -0,0 +1,154 @@
+"""Prepare a real, small coding WorkOrder for the TUI; make no model calls."""
+
+from __future__ import annotations
+
+import argparse
+import shlex
+import subprocess
+import sys
+from pathlib import Path
+
+import yaml
+
+from superqode.harness.loader import load_harness_spec
+from superqode.workorders import (
+    WorkOrder,
+    WorkOrderBudget,
+    WorkOrderStore,
+    WorkOrderTask,
+    WorkTaskRole,
+)
+
+
+def prepare(directory: Path, *, provider: str, model: str, recovery=False):
+    directory = directory.expanduser().resolve()
+    directory.mkdir(parents=True, exist_ok=False)
+    (directory / "answer.py").write_text("def answer():\n    return 41\n")
+    (directory / "test_answer.py").write_text(
+        "import unittest\nfrom answer import answer\n\n"
+        "class AnswerTest(unittest.TestCase):\n"
+        "    def test_answer(self):\n        self.assertEqual(answer(), 42)\n"
+    )
+    (directory / "AGENTS.md").write_text(
+        "Keep the change minimal. Never modify test_answer.py. Run the acceptance test.\n"
+    )
+    (directory / ".gitignore").write_text(".superqode/\n__pycache__/\n")
+    subprocess.run(["git", "init", "-q", str(directory)], check=True)
+    subprocess.run(["git", "-C", str(directory), "add", "."], check=True)
+    subprocess.run(
+        [
+            "git",
+            "-C",
+            str(directory),
+            "-c",
+            "user.name=SuperQode Demo",
+            "-c",
+            "user.email=demo@example.invalid",
+            "commit",
+            "-qm",
+            "Failing answer acceptance test",
+        ],
+        check=True,
+    )
+    control = directory / ".superqode"
+    control.mkdir()
+    harness = {
+        "version": 1,
+        "name": "tui-demo-pipy",
+        "flavor": "coding",
+        "runtime": {
+            "backend": "pipy",
+            "config": {"recovery": {"enabled": recovery}, "mcp_config": False},
+        },
+        "model_policy": {"primary": model, "config": {"provider": provider}},
+        "execution_policy": {
+            "sandbox": "none",
+            "allow_read": True,
+            "allow_write": True,
+            "allow_shell": True,
+            "allow_network": False,
+        },
+        "agents": [
+            {
+                "id": "coder",
+                "role": "implementation",
+                "system_prompt": "Inspect the assigned task, make only requested changes, and finish with concise evidence.",
+            }
+        ],
+    }
+    harness_path = control / "demo-pipy.yaml"
+    harness_path.write_text(yaml.safe_dump(harness, sort_keys=False))
+    load_harness_spec(harness_path)
+    investigate = control / "demo-investigate.yaml"
+    harness["name"] = "tui-demo-investigate"
+    harness["execution_policy"]["allow_write"] = False
+    investigate.write_text(yaml.safe_dump(harness, sort_keys=False))
+    load_harness_spec(investigate)
+    store = WorkOrderStore(control / "workorders" / "store.sqlite3")
+    acceptance = f"{shlex.quote(sys.executable)} -m unittest -v"
+    store.create(
+        WorkOrder(
+            "tui-demo",
+            "Fix answer() to satisfy the unchanged acceptance test",
+            str(directory),
+            acceptance_tests=(acceptance,),
+            harness=str(harness_path),
+            budget=WorkOrderBudget(max_seconds=900, max_workers=1, max_tool_calls=20),
+            metadata={"evidence_reuse": True},
+            tasks=(
+                WorkOrderTask(
+                    "investigate",
+                    "Investigate the failing answer",
+                    "Read answer.py and test_answer.py, run the acceptance test, report the cause and smallest fix. Do not edit files.",
+                    role=WorkTaskRole.INVESTIGATOR,
+                    harness=str(investigate),
+                    provider=provider,
+                    model=model,
+                    max_attempts=4,
+                ),
+                WorkOrderTask(
+                    "implement",
+                    "Implement and verify the fix",
+                    "Retrieve assigned investigator evidence. Fix answer.py only, keep test_answer.py unchanged, run the acceptance test and report its outcome.",
+                    dependencies=("investigate",),
+                    harness=str(harness_path),
+                    provider=provider,
+                    model=model,
+                    max_attempts=4,
+                ),
+            ),
+        )
+    )
+    store.queue("tui-demo")
+    return directory
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "directory", type=Path, help="New directory; existing directories are refused"
+    )
+    parser.add_argument("--provider", required=True)
+    parser.add_argument("--model", required=True)
+    parser.add_argument(
+        "--recovery",
+        action="store_true",
+        help="Explicitly enable experimental PiPy process recovery",
+    )
+    args = parser.parse_args()
+    root = prepare(args.directory, provider=args.provider, model=args.model, recovery=args.recovery)
+    print(
+        f"Prepared {root}; no model calls made. Recovery: {'enabled' if args.recovery else 'off'}."
+    )
+    print(f"cd {shlex.quote(str(root))}\nsq\n:work view tui-demo --lease 10")
+    print("Select Run ready tasks, then Execute. Inspect Evidence and Recovery while it runs.")
+    print(
+        "After completion: Acceptance checks, Prepare candidate, Review / Open, then Approve with your reason."
+    )
+    print(
+        "Workers use the selected provider and may incur cost. This demo uses process permissions; it does not configure an OS sandbox."
+    )
+
+
+if __name__ == "__main__":
+    main()

{superqode-2.5.4 → superqode-2.5.6}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "superqode"
-version = "2.5.4"
+version = "2.5.6"
 description = "The harness layer for coding agents"
 readme = "README.md"
 license = "Apache-2.0"

{superqode-2.5.4 → superqode-2.5.6}/src/superqode/__init__.py

@@ -38,7 +38,7 @@ __all__ = [
     "sidebar",
 ]
 
-__version__ = "2.5.4"
+__version__ = "2.5.6"
 
 # Stable, lightweight public extension surface.  Importing this package does
 # not discover or execute third-party extensions; discovery happens only when

superqode-2.5.6/src/superqode/a2a/billing.py

@@ -0,0 +1,159 @@
+"""Integer task credits and skill entitlements, independent of signed keys.
+
+Use one authoritative database shared by workers. Disconnects and ambiguous
+execution keep their reservation until an operator reconciles it.
+"""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+import json
+from pathlib import Path
+import sqlite3
+import time
+
+
+class CreditLedger:
+    def __init__(self, path: str | Path):
+        self.path = Path(path).expanduser().resolve()
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        with self.transaction() as conn:
+            conn.executescript("""
+              create table if not exists a2a_accounts (
+                customer text primary key, balance integer not null, reserved integer not null,
+                skills text not null, expires real not null, max_parallel integer not null);
+              create table if not exists a2a_credit_jobs (
+                id text primary key, customer text not null, fingerprint text not null,
+                credits integer not null, state text not null, charged integer, updated real not null);
+              create table if not exists a2a_credit_audit (
+                seq integer primary key autoincrement, customer text not null,
+                job text not null, action text not null, data text not null, observed real not null);
+            """)
+        self.path.chmod(0o600)
+
+    @contextmanager
+    def transaction(self):
+        conn = sqlite3.connect(self.path, timeout=30)
+        conn.row_factory = sqlite3.Row
+        conn.execute("pragma journal_mode=wal")
+        conn.execute("pragma synchronous=full")
+        conn.execute("begin immediate")
+        try:
+            yield conn
+            conn.commit()
+        except BaseException:
+            conn.rollback()
+            raise
+        finally:
+            conn.close()
+
+    def grant(self, customer, credits, *, skills, expires_at, max_parallel=1):
+        if (
+            not customer
+            or isinstance(credits, bool)
+            or not isinstance(credits, int)
+            or credits < 0
+            or not skills
+            or expires_at <= time.time()
+            or not 1 <= max_parallel <= 64
+        ):
+            raise ValueError(
+                "Credits require a customer, integer allowance, skills, future expiry and bounded concurrency"
+            )
+        with self.transaction() as conn:
+            conn.execute(
+                "insert into a2a_accounts values (?,?,0,?,?,?) on conflict(customer) do update set balance=balance+excluded.balance,skills=excluded.skills,expires=excluded.expires,max_parallel=excluded.max_parallel",
+                (customer, credits, json.dumps(list(skills)), expires_at, max_parallel),
+            )
+            conn.execute(
+                "insert into a2a_credit_audit(customer,job,action,data,observed) values (?,?,'grant',?,?)",
+                (
+                    customer,
+                    "",
+                    json.dumps({"credits": credits, "skills": list(skills), "expires": expires_at}),
+                    time.time(),
+                ),
+            )
+        return self.account(customer)
+
+    def account(self, customer):
+        with self.transaction() as conn:
+            row = conn.execute(
+                "select * from a2a_accounts where customer=?", (customer,)
+            ).fetchone()
+            if row is None:
+                raise PermissionError("No hosted service account")
+            return {
+                **dict(row),
+                "skills": json.loads(row["skills"]),
+                "available": row["balance"] - row["reserved"],
+            }
+
+    def reserve(self, customer, job, fingerprint, *, skill, credits):
+        if isinstance(credits, bool) or not isinstance(credits, int) or credits <= 0:
+            raise ValueError("A hosted task requires a positive integer credit tariff")
+        with self.transaction() as conn:
+            existing = conn.execute("select * from a2a_credit_jobs where id=?", (job,)).fetchone()
+            if existing:
+                if existing["customer"] != customer or existing["fingerprint"] != fingerprint:
+                    raise PermissionError("Computational work ID belongs to another request")
+                return dict(existing), False
+            account = conn.execute(
+                "select * from a2a_accounts where customer=?", (customer,)
+            ).fetchone()
+            if (
+                account is None
+                or account["expires"] <= time.time()
+                or skill not in json.loads(account["skills"])
+            ):
+                raise PermissionError("Hosted skill entitlement is missing or expired")
+            active = conn.execute(
+                "select count(*) from a2a_credit_jobs where customer=? and state='reserved'",
+                (customer,),
+            ).fetchone()[0]
+            if (
+                active >= account["max_parallel"]
+                or account["balance"] - account["reserved"] < credits
+            ):
+                raise PermissionError("Hosted credit or concurrency allowance exhausted")
+            conn.execute(
+                "update a2a_accounts set reserved=reserved+? where customer=?", (credits, customer)
+            )
+            conn.execute(
+                "insert into a2a_credit_jobs values (?,?,?,?, 'reserved',NULL,?)",
+                (job, customer, fingerprint, credits, time.time()),
+            )
+            return {"id": job, "customer": customer, "credits": credits, "state": "reserved"}, True
+
+    def settle(self, customer, job, charged, *, reason="execution finished"):
+        if not isinstance(reason, str) or not reason.strip():
+            raise ValueError("Credit settlement requires an audit reason")
+        with self.transaction() as conn:
+            row = conn.execute(
+                "select * from a2a_credit_jobs where id=? and customer=?", (job, customer)
+            ).fetchone()
+            if row is None:
+                raise PermissionError("Unknown hosted reservation")
+            if (
+                isinstance(charged, bool)
+                or not isinstance(charged, int)
+                or not 0 <= charged <= row["credits"]
+            ):
+                raise ValueError("Settlement must fit the admitted integer tariff")
+            if row["state"] == "settled":
+                if row["charged"] != charged:
+                    raise ValueError("Reservation already settled for a different amount")
+                return False
+            conn.execute(
+                "update a2a_accounts set balance=balance-?,reserved=reserved-? where customer=?",
+                (charged, row["credits"], customer),
+            )
+            conn.execute(
+                "update a2a_credit_jobs set state='settled',charged=?,updated=? where id=?",
+                (charged, time.time(), job),
+            )
+            conn.execute(
+                "insert into a2a_credit_audit(customer,job,action,data,observed) values (?,?,'settle',?,?)",
+                (customer, job, json.dumps({"charged": charged, "reason": reason}), time.time()),
+            )
+            return True