superqode 2.5.2__tar.gz → 2.5.3__tar.gz

{superqode-2.5.2 → superqode-2.5.3}/CHANGELOG.md

@@ -7,6 +7,50 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.5.3] - 2026-10-03
+
+### Highlights
+
+- Harden WorkOrder submission, lifecycle replay and predecessor evidence reuse.
+  Add opt-in context controls compatible with Jev's bounded decision approach,
+  shared by Core and hosted PiPy. Core remains the default harness.
+- Context selection defaults to `off`; predecessor evidence reuse requires
+  `--reuse-evidence`. Start with `mode: shadow` and `selector: rules` to inspect
+  proposed excerpts without changing the prompt or calling a selector service.
+
+### Added
+
+- Retry-safe WorkOrder admission with `--request-id`: matching requests return
+  the existing order, while changed contracts fail. Creation and queueing commit
+  atomically. Persisted event sequences support restartable cursor replay.
+- Durable, sanitized context references with bounded retrieval, integrity
+  checks, owner isolation and current permission checks. Context projections
+  preserve original session history and protected instructions and evidence.
+- Opt-in predecessor evidence catalogs with source and lineage freshness checks,
+  exposed through `sq work evidence` and assigned worker retrieval.
+- Optional bounded Jev context selection with evidence previews, decision reuse,
+  local triggers, timeouts and call limits. Failures retain evidence; unreserved
+  selector calls are disabled in cost/token-capped WorkOrders.
+- Typed Pydantic tools for the PiPy SDK, inherited project resources and opt-in
+  conditional instruction matching in hosted PiPy.
+- An offline hardening demo at `examples/workorders/hardening_demo.py` and
+  context diagnostics in run history and matched benchmark reports.
+
+### Fixed
+
+- Validate recovery operation identity before reusing saved outcomes. Strengthen
+  matched benchmark grading, protected graders, model identity and accounting.
+- Include `:work evidence` in TUI completion and run native context and WorkOrder
+  contract checks before publishing. Align commit-hook formatting with locked CI.
+
+### Notes
+
+- Jev selection is experimental and requires a working System One connection.
+  The rule-based demo requires no model key and makes no inference calls.
+- Evidence freshness and reported findings do not replace acceptance tests or
+  candidate review. Character reductions are not measured provider-token savings.
+- This release does not claim complete Pi parity or live Pi/Jev superiority.
+
 ## [2.5.2] - 2026-10-03
 
 ### Fixed

{superqode-2.5.2 → superqode-2.5.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: superqode
-Version: 2.5.2
+Version: 2.5.3
 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.3/examples/pipy/typed_tool.py

@@ -0,0 +1,49 @@
+"""Pydantic input models and live progress through the offline PiPy SDK."""
+
+import asyncio
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from superqode.pipy import (
+    AgentHarness,
+    AgentToolResult,
+    MemorySessionStorage,
+    Model,
+    ToolCall,
+    ToolContext,
+    create_session,
+    create_typed_tool,
+)
+from superqode.pipy.ai import FakeStream, text_response, tool_response
+
+
+class Lookup(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    key: str = Field(min_length=1)
+    limit: int = Field(default=3, ge=1, le=10)
+
+
+async def lookup(args: Lookup, context: ToolContext) -> AgentToolResult:
+    context.check_cancelled()
+    context.emit(AgentToolResult(content="Looking up records"))
+    return AgentToolResult(content=f"Found {args.key}", details=args.model_dump())
+
+
+async def main():
+    tool = create_typed_tool("lookup", "Read example records", Lookup, lookup, replay_safe=True)
+    harness = AgentHarness(
+        session=await create_session(MemorySessionStorage()),
+        model=Model(id="offline", provider="fixture"),
+        tools=[tool],
+        stream_fn=FakeStream(
+            [
+                tool_response(ToolCall(id="lookup-1", name="lookup", arguments={"key": "example"})),
+                text_response("Typed tool completed."),
+            ]
+        ),
+    )
+    print((await harness.prompt("Find the example")).text)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

superqode-2.5.3/examples/workorders/hardening_demo.py

@@ -0,0 +1,166 @@
+"""Offline WorkOrder/context mechanics demo; no model requests or credentials.
+
+Run: python examples/workorders/hardening_demo.py [--directory NEW_DIRECTORY]
+The synthetic finding is labelled reported, not independently verified.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+from dataclasses import replace
+import json
+from pathlib import Path
+import subprocess
+import tempfile
+from types import SimpleNamespace
+
+from superqode.harness.context_artifacts import ContextArtifactStore
+from superqode.harness.context_policy import ContextItem, ContextPolicy, ContextPolicyEngine
+from superqode.workorders import WorkOrder, WorkOrderStore, WorkOrderTask, WorkTaskRole
+from superqode.workorders.evidence import (
+    dependency_catalog,
+    publish_evidence,
+    read_workorder_evidence,
+)
+
+
+async def demonstrate(directory: Path) -> dict:
+    repo = directory / "repo"
+    repo.mkdir()
+    source = repo / "app.py"
+    source.write_text("def answer():\n    return 0\n", encoding="utf-8")
+    for args in (
+        ("init", "-q"),
+        ("add", "app.py"),
+        (
+            "-c",
+            "user.name=Demo",
+            "-c",
+            "user.email=demo@example.invalid",
+            "commit",
+            "-qm",
+            "Demo fixture",
+        ),
+    ):
+        subprocess.run(["git", "-C", str(repo), *args], check=True, capture_output=True)
+
+    investigate = WorkOrderTask(
+        "investigate", "Investigate", "Inspect answer()", role=WorkTaskRole.INVESTIGATOR
+    )
+    implement = WorkOrderTask(
+        "implement", "Implement", "Repair answer()", dependencies=("investigate",)
+    )
+    store = WorkOrderStore(directory / "work.sqlite3")
+    order = WorkOrder(
+        "work-hardening-demo",
+        "Demonstrate durable evidence and retry-safe admission",
+        str(repo),
+        harness="pipy",
+        tasks=(investigate, implement),
+        metadata={
+            "evidence_reuse": {"enabled": True, "store_path": str(directory / "evidence.sqlite3")}
+        },
+    )
+    admitted = store.create(order, request_id="demo-request-1", queue=True)
+    retry = WorkOrderStore(store.path).create(
+        replace(order, work_order_id="retry-generated-id"), request_id="demo-request-1", queue=True
+    )
+    assert retry.work_order_id == admitted.work_order_id
+    store.claim_next_task(reference=admitted.work_order_id, worker_id="demo-worker")
+    artifact = publish_evidence(
+        store,
+        admitted,
+        investigate,
+        "Synthetic finding: app.py answer() currently returns 0.",
+        repo,
+    )
+    store.complete_task(admitted.work_order_id, investigate.task_id, worker_id="demo-worker")
+    order = WorkOrderStore(store.path).get(admitted.work_order_id)
+    catalog = dependency_catalog(order, implement, repo)
+    assert catalog[0]["freshness"] == "current"
+    scope = SimpleNamespace(
+        store=store, work_order_id=order.work_order_id, task_id=implement.task_id
+    )
+    page = read_workorder_evidence(scope, artifact.metadata["reference"], repo, limit=1000)
+    assert "Synthetic finding" in page.text
+    source.write_text("def answer():\n    return 42\n", encoding="utf-8")
+    assert dependency_catalog(order, implement, repo)[0]["freshness"] == "stale"
+
+    first = store.events(order.work_order_id, after_sequence=0, limit=2)
+    rest = WorkOrderStore(store.path).events(order.work_order_id, after_sequence=first[-1].sequence)
+    assert first + rest == store.events(order.work_order_id)
+
+    original = "Synthetic old tool evidence: answer() returns 0.\n" * 300
+    history = [
+        ContextItem("user-1", "user", "Inspect app.py"),
+        ContextItem("call-1", "assistant", "Read app.py"),
+        ContextItem("result-1", "tool", original, "read_file", "read-1", {"path": "app.py"}),
+        ContextItem("assistant-2", "assistant", "Continue"),
+        ContextItem("user-2", "user", "Repair answer() in app.py"),
+    ]
+    contexts = ContextArtifactStore(directory / "context.sqlite3")
+    shadow = await ContextPolicyEngine(
+        contexts, "demo-session", ContextPolicy(mode="shadow", recent_messages=1)
+    ).prepare(history)
+    assert shadow.replacements == {}
+    assert shadow.trace["proposed_chars_after"] < shadow.trace["chars_before"]
+    enforced = await ContextPolicyEngine(
+        contexts, "demo-session", ContextPolicy(mode="enforce", recent_messages=1)
+    ).prepare(history)
+    assert len(enforced.replacements[2]) < len(original)
+    reference = enforced.decisions[0].reference
+    restored = ContextArtifactStore(contexts.path).read_page(
+        "demo-session", reference, offset=30, limit=100
+    )
+    assert restored.text == original[30:130]
+    assert history[2].text == original
+
+    return {
+        "directory": str(directory),
+        "work_order_id": order.work_order_id,
+        "inference_calls": 0,
+        "duplicate_submission": "same WorkOrder; no requeue",
+        "event_cursor_restart": "no missing or repeated events",
+        "evidence_verification": catalog[0]["verification"],
+        "source_freshness": "current -> stale after app.py changes",
+        "shadow": {
+            "original_characters": shadow.trace["chars_before"],
+            "proposed_characters": shadow.trace["proposed_chars_after"],
+            "prompt_changed": False,
+        },
+        "opt_in_rules_enforcement": "excerpt with retrievable reference; original retained",
+        "reference_restart": "exact bounded page restored",
+        "jev_service": "not called; this demonstrates compatible engineering mechanics",
+    }
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--directory", type=Path, help="A new directory for the fixture and persisted artifacts"
+    )
+    args = parser.parse_args()
+    if args.directory:
+        directory = args.directory.expanduser().resolve()
+        if directory.exists():
+            parser.error("--directory must not already exist")
+        directory.mkdir(parents=True)
+    else:
+        directory = Path(tempfile.mkdtemp(prefix="superqode-hardening-demo-"))
+    result = asyncio.run(demonstrate(directory))
+    (directory / "demo-result.json").write_text(
+        json.dumps(result, indent=2) + "\n", encoding="utf-8"
+    )
+    print(json.dumps(result, indent=2))
+    print("\nInspect the persisted demo:")
+    print(
+        f"sq work --store {directory / 'work.sqlite3'} events {result['work_order_id']} --after-sequence 0 --json"
+    )
+    print(
+        f"sq work --store {directory / 'work.sqlite3'} evidence {result['work_order_id']} --task implement --json"
+    )
+
+
+if __name__ == "__main__":
+    main()

{superqode-2.5.2 → superqode-2.5.3}/pyproject.toml

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

{superqode-2.5.2 → superqode-2.5.3}/src/superqode/__init__.py

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

{superqode-2.5.2 → superqode-2.5.3}/src/superqode/agent/hooks.py

@@ -62,6 +62,8 @@ SESSION_START = "session_start"
 USER_PROMPT_SUBMIT = "user_prompt_submit"
 BEFORE_LLM_CALL = "before_llm_call"
 AFTER_LLM_CALL = "after_llm_call"
+CONTEXT_SELECTION = "context_selection"
+CONTEXT_RETRIEVAL = "context_retrieval"
 PERMISSION_REQUEST = "permission_request"
 BEFORE_TOOL_CALL = "before_tool_call"
 AFTER_TOOL_CALL = "after_tool_call"
@@ -75,6 +77,8 @@ ALL_HOOK_POINTS = (
     USER_PROMPT_SUBMIT,
     BEFORE_LLM_CALL,
     AFTER_LLM_CALL,
+    CONTEXT_SELECTION,
+    CONTEXT_RETRIEVAL,
     PERMISSION_REQUEST,
     BEFORE_TOOL_CALL,
     AFTER_TOOL_CALL,
@@ -300,6 +304,8 @@ __all__ = [
     "USER_PROMPT_SUBMIT",
     "BEFORE_LLM_CALL",
     "AFTER_LLM_CALL",
+    "CONTEXT_SELECTION",
+    "CONTEXT_RETRIEVAL",
     "PERMISSION_REQUEST",
     "BEFORE_TOOL_CALL",
     "AFTER_TOOL_CALL",

{superqode-2.5.2 → superqode-2.5.3}/src/superqode/agent/loop.py

@@ -1391,6 +1391,50 @@ class AgentLoop:
 
         return context_original(self, chunk_id)
 
+    def _context_page(self, chunk_id: str, *, offset: int = 0, limit: int = 4000):
+        from ..harness.context_artifacts import ContextArtifactStore, originating_tool
+
+        store = getattr(self, "_context_artifact_store", None)
+        if store is None:
+            spec = getattr(self.config, "harness_spec", None)
+            settings = (getattr(getattr(spec, "runtime", None), "config", None) or {}).get(
+                "context", {}
+            )
+            store = ContextArtifactStore(settings.get("store_path"))
+        if not chunk_id.startswith("ctx_"):
+            chunk_id = store.resolve_alias(self.session_id, chunk_id)
+        try:
+            record = store.describe(self.session_id, chunk_id)
+            manager = getattr(self, "permission_manager", None)
+            if manager is not None:
+                from ..tools.permissions import Permission
+
+                if (
+                    manager.check_permission(
+                        originating_tool(record.metadata), record.metadata.get("arguments", {})
+                    )
+                    == Permission.DENY
+                ):
+                    raise PermissionError("Originating resource permission revoked")
+            return store.read_page(self.session_id, chunk_id, offset=offset, limit=limit)
+        except LookupError:
+            from superqode.execution_recovery import active_recovery
+            from ..workorders.evidence import read_workorder_evidence
+
+            return read_workorder_evidence(
+                active_recovery(),
+                chunk_id,
+                self.config.working_directory,
+                offset=offset,
+                limit=limit,
+                permission_manager=getattr(self, "permission_manager", None),
+            )
+
+    async def _prepare_host_context(self, messages):
+        from ..harness.core_context import prepare_core_context
+
+        return await prepare_core_context(self, messages)
+
     def _create_tool_context(self) -> ToolContext:
         """Create context for tool execution."""
         return ToolContext(
@@ -1404,6 +1448,7 @@ class AgentLoop:
             permission_manager=self.permission_manager,
             context_status=self._context_status,
             context_chunk=self._context_chunk,
+            context_page=self._context_page,
             systemone=self.config.systemone,
             systemone_client=self._systemone_client,
             harness_store=self.config.harness_store,
@@ -1685,16 +1730,18 @@ class AgentLoop:
         hooks see every attempted call.
         """
         from ..acp.tool_call_context import acp_tool_call_context
-        from .hooks import AFTER_TOOL_CALL, BEFORE_TOOL_CALL
+        from .hooks import AFTER_TOOL_CALL, BEFORE_TOOL_CALL, CONTEXT_RETRIEVAL
 
         lifecycle_ctx = self._lifecycle_context()
 
         async def _finalize(result: ToolResult) -> ToolResult:
             import hashlib
+            from ..systemone.state import redact_evidence
 
             result.metadata = {
                 **(result.metadata or {}),
                 "invocation_id": tool_call_id,
+                "source_arguments": redact_evidence(arguments),
                 "effective_arguments_sha256": hashlib.sha256(
                     json.dumps(arguments, sort_keys=True, default=str).encode()
                 ).hexdigest(),
@@ -1722,7 +1769,20 @@ class AgentLoop:
                         }
                     )
                     self.last_discovery_event = {**current, "executions": executions[-10:]}
-            result = self._bound_tool_result(name, result)
+            result = self._bound_tool_result(name, result, arguments=arguments)
+            if name == "read_context_chunk":
+                await self.hooks.fire(
+                    CONTEXT_RETRIEVAL,
+                    lifecycle_ctx,
+                    {
+                        "kind": "context_retrieval",
+                        "success": result.success,
+                        "reference": str(arguments.get("chunk_id", ""))[:128],
+                        "offset": (result.metadata or {}).get("offset"),
+                        "next_offset": (result.metadata or {}).get("next_offset"),
+                        "chars": len(result.output),
+                    },
+                )
             await self.hooks.fire(AFTER_TOOL_CALL, lifecycle_ctx, name, arguments, result)
             return result
 
@@ -2302,7 +2362,7 @@ class AgentLoop:
         )
         return result_messages
 
-    def _bound_tool_result(self, name: str, result: ToolResult) -> ToolResult:
+    def _bound_tool_result(self, name: str, result: ToolResult, *, arguments=None) -> ToolResult:
         """Last-resort output bound for tools that don't self-limit.
 
         Bash and read_file already size themselves to the model; this guard
@@ -2313,6 +2373,68 @@ class AgentLoop:
         notice after their own truncation aren't truncated twice.
         """
         output = result.output or ""
+        from ..harness.core_context import configured_context_policy
+
+        spec = getattr(self.config, "harness_spec", None)
+        context_config = (getattr(getattr(spec, "runtime", None), "config", None) or {}).get(
+            "context", {}
+        )
+        policy = configured_context_policy(context_config)
+        if policy and len(output) >= policy.min_chars:
+            try:
+                import hashlib
+                from ..harness.context_artifacts import ContextArtifactStore
+                from ..harness.context_policy import (
+                    ContextCandidate,
+                    evidence_preview,
+                    reference_excerpt,
+                )
+                from ..systemone.state import redact_evidence
+
+                store = getattr(self, "_context_artifact_store", None) or ContextArtifactStore(
+                    context_config.get("store_path")
+                )
+                record = store.put(
+                    self.session_id,
+                    f"invocation:{result.metadata.get('invocation_id', '')}:{hashlib.sha256(output.encode()).hexdigest()}",
+                    output,
+                    metadata={
+                        "tool": name,
+                        "arguments": arguments or {},
+                        "success": result.success,
+                        "upstream_truncated": bool(result.metadata.get("truncated")),
+                    },
+                )
+                self._context_artifact_store = store
+                self._ensure_context_chunk_tool()
+                cap = self._tool_output_byte_cap or 100_000
+                if len(output.encode()) > cap:
+                    excerpt = reference_excerpt(
+                        ContextCandidate(
+                            0,
+                            record.reference,
+                            record.digest,
+                            evidence_preview(
+                                redact_evidence(output),
+                                "",
+                                min(policy.excerpt_chars, max(100, cap // 4)),
+                            ),
+                            record.chars,
+                            name,
+                        )
+                    )
+                    return ToolResult(
+                        result.success,
+                        excerpt,
+                        result.error,
+                        {
+                            **result.metadata,
+                            "context_reference": record.reference,
+                            "loop_truncated": True,
+                        },
+                    )
+            except Exception:
+                pass  # Existing bounded-output behavior remains available.
         cap = self._tool_output_byte_cap or 100_000
         limit = int(cap * 1.25) + 512
         if len(output) <= limit:  # cheap pre-check; chars <= bytes
@@ -2710,6 +2832,7 @@ class AgentLoop:
                     f"Steering: picked up {len(drained)} queued user message(s)."
                 )
             messages = self._refresh_opt_in_instructions(messages)
+            model_messages = await self._prepare_host_context(messages)
 
             # Tool definitions are per-iteration: tool_search may have
             # activated deferred tools since the last call.
@@ -2726,9 +2849,9 @@ class AgentLoop:
 
             # PERFORMANCE: Use cached message conversion. Reminders ride along
             # on the request only - they are not part of stored history.
-            request_messages = messages
+            request_messages = model_messages
             if not fast_chat:
-                request_messages = messages + self._collect_reminder_messages(
+                request_messages = model_messages + self._collect_reminder_messages(
                     iterations, user_message
                 )
             gateway_messages = self._convert_messages(request_messages)
@@ -3222,6 +3345,7 @@ class AgentLoop:
                     f"Steering: picked up {len(drained)} queued user message(s)."
                 )
             messages = self._refresh_opt_in_instructions(messages)
+            model_messages = await self._prepare_host_context(messages)
 
             # Tool definitions are per-iteration: tool_search may have
             # activated deferred tools since the last call.
@@ -3236,9 +3360,9 @@ class AgentLoop:
 
             # PERFORMANCE: Use cached message conversion. Reminders ride along
             # on the request only - they are not part of stored history.
-            request_messages = messages
+            request_messages = model_messages
             if not fast_chat:
-                request_messages = messages + self._collect_reminder_messages(
+                request_messages = model_messages + self._collect_reminder_messages(
                     iterations, user_message
                 )
             gateway_messages = self._convert_messages(request_messages)

{superqode-2.5.2 → superqode-2.5.3}/src/superqode/app/constants.py

@@ -703,6 +703,7 @@ COMMANDS = [
     ":work check",
     ":work artifact-add",
     ":work artifacts",
+    ":work evidence",
     ":work events",
     ":work programs",
     ":work program-run",