superqode 0.2.7__tar.gz → 0.2.8__tar.gz

{superqode-0.2.7 → superqode-0.2.8}/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.8] - 2026-07-07
+
+### Added
+
+- **Self-improving harness loop** - Added `harness mine-failures`, `harness logbook`, and `harness improve` workflows for mining failures, maintaining repo-local harness memory, exporting bounded improvement projects, and feeding evidence into candidate generation.
+- **Candidate audit and ledger** - Added `harness audit-candidate` plus `harness candidates list/show/export` to record accepted and rejected harness candidates, detect protected-surface edits, permission widening, weakened checks, duplicate rejected edits, and missing held-out gates.
+- **Held-in / held-out eval splits** - Added split-aware eval tasks and `harness eval --split {all,held-in,held-out}` so candidate improvements can be gated separately from training/proposal tasks.
+- **Harness usage metrics** - Harness runs and eval scorecards now aggregate token, latency, and cost metrics where providers expose them.
+- **Self-improvement docs** - Documented the end-to-end loop, optimization policy fields, candidate audit gates, candidate ledger, and logbook pruning.
+
+### Changed
+
+- **Release metadata** - Bumped the package version, runtime `__version__`, lockfile package entry, and ACP registry metadata to `0.2.8`.
+
 ## [0.2.7] - 2026-07-05
 
 ### Fixed

{superqode-0.2.7/src/superqode.egg-info → superqode-0.2.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: superqode
-Version: 0.2.7
+Version: 0.2.8
 Summary: SuperQode: harness engineering framework for coding agents, optimized for local and open models
 Author-email: Shashi Jagtap <info@super-agentic.ai>
 Maintainer-email: Shashi Jagtap <info@super-agentic.ai>

{superqode-0.2.7 → superqode-0.2.8}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "superqode"
-version = "0.2.7"
+version = "0.2.8"
 description = "SuperQode: harness engineering framework for coding agents, optimized for local and open models"
 readme = "README.md"
 license = "Apache-2.0"

{superqode-0.2.7 → superqode-0.2.8}/src/superqode/__init__.py

@@ -30,4 +30,4 @@ __all__ = [
     "sidebar",
 ]
 
-__version__ = "0.2.7"
+__version__ = "0.2.8"

{superqode-0.2.7 → superqode-0.2.8}/src/superqode/acp/server.py

@@ -46,6 +46,7 @@ from acp.schema import (
     PermissionOption,
     PromptCapabilities,
     TerminalAuthMethod,
+    ToolCallLocation,
     ToolCallUpdate,
 )
 
@@ -98,6 +99,74 @@ def _tool_kind(name: str) -> str:
     return "other"
 
 
+# Argument keys that carry the tool's target, by role. Cover both snake_case and
+# camelCase spellings since specs and external runtimes disagree on convention.
+_PATH_ARG_KEYS = ("file_path", "filePath", "path", "file", "abs_path", "filename", "target_file")
+_COMMAND_ARG_KEYS = ("command", "cmd", "script")
+_PATTERN_ARG_KEYS = ("pattern", "query", "regex", "search")
+_URL_ARG_KEYS = ("url", "uri")
+
+_TITLE_LIMIT = 120
+
+
+def _first_str(args: dict[str, Any], keys: tuple[str, ...]) -> str:
+    for key in keys:
+        value = args.get(key)
+        if isinstance(value, str) and value.strip():
+            return value.strip()
+    return ""
+
+
+def _clip_title(text: str) -> str:
+    text = " ".join(text.split())
+    if len(text) <= _TITLE_LIMIT:
+        return text
+    return text[: _TITLE_LIMIT - 1] + "…"
+
+
+def _tool_title(name: str, arguments: Any) -> str:
+    """Human-readable tool_call title: verb + target, not just the tool name.
+
+    Editors surface ``title`` directly (Zed, JetBrains) while ``raw_input`` is
+    hidden behind an expander, so the file path / command must be in the title.
+    """
+    args = arguments if isinstance(arguments, dict) else {}
+    kind = _tool_kind(name)
+    path = _first_str(args, _PATH_ARG_KEYS)
+    if kind == "execute":
+        command = _first_str(args, _COMMAND_ARG_KEYS)
+        return _clip_title(command) if command else name
+    if kind == "read" and path:
+        return _clip_title(f"Read {path}")
+    if kind == "edit" and path:
+        verb = "Write" if "write" in name.lower() or "create" in name.lower() else "Edit"
+        return _clip_title(f"{verb} {path}")
+    if kind == "search":
+        pattern = _first_str(args, _PATTERN_ARG_KEYS)
+        if pattern:
+            return _clip_title(f"Search {pattern}" + (f" in {path}" if path else ""))
+    if kind == "fetch":
+        url = _first_str(args, _URL_ARG_KEYS)
+        if url:
+            return _clip_title(f"Fetch {url}")
+    if path:
+        return _clip_title(f"{name} {path}")
+    return name
+
+
+def _tool_locations(arguments: Any) -> list[ToolCallLocation] | None:
+    """File locations for follow-the-agent UIs, when the arguments name a path."""
+    args = arguments if isinstance(arguments, dict) else {}
+    path = _first_str(args, _PATH_ARG_KEYS)
+    if not path:
+        return None
+    location = ToolCallLocation(path=path)
+    line = args.get("line") or args.get("start_line") or args.get("offset")
+    if isinstance(line, int) and line > 0:
+        location.line = line
+    return [location]
+
+
 def _prompt_to_text(blocks: list[Any] | None) -> str:
     """Flatten ACP prompt content blocks into one harness prompt string."""
     parts: list[str] = []
@@ -430,32 +499,55 @@ class SuperQodeAcpAgent:
                 await self._send_update(session_id, update_agent_thought_text(text))
         elif event_type == "tool_call":
             name = str(data.get("tool_name") or "tool")
+            arguments = data.get("arguments")
             call_id = tracker.start(name)
             await self._send_update(
                 session_id,
                 start_tool_call(
                     call_id,
-                    name,
+                    _tool_title(name, arguments),
                     kind=_tool_kind(name),
                     status="in_progress",
-                    raw_input=data.get("arguments"),
+                    locations=_tool_locations(arguments),
+                    raw_input=arguments,
                 ),
             )
         elif event_type == "tool_result":
             name = str(data.get("tool_name") or "tool")
             call_id = tracker.finish(name)
-            if call_id is None:
-                return
             success = data.get("success", True)
             output = data.get("output") if success else (data.get("error") or data.get("output"))
             content = []
             if output:
                 content.append(tool_content(text_block(_clip(output))))
+            status = "completed" if success else "failed"
+            if call_id is None:
+                # Runtimes like codex-sdk report tools only on completion; synthesize
+                # the tool_call rather than dropping the result on the floor.
+                arguments = data.get("arguments") or {
+                    key: data[key] for key in ("command", "path") if data.get(key)
+                }
+                call_id = tracker.start(name)
+                tracker.finish(name)
+                await self._send_update(
+                    session_id,
+                    start_tool_call(
+                        call_id,
+                        _tool_title(name, arguments),
+                        kind=_tool_kind(name),
+                        status=status,
+                        locations=_tool_locations(arguments),
+                        raw_input=arguments or None,
+                        content=content or None,
+                        raw_output=output,
+                    ),
+                )
+                return
             await self._send_update(
                 session_id,
                 update_tool_call(
                     call_id,
-                    status="completed" if success else "failed",
+                    status=status,
                     content=content or None,
                     raw_output=output,
                 ),
@@ -472,6 +564,7 @@ class SuperQodeAcpAgent:
                 return True
             item = dict(pending[0])
             tool_name = str(item.get("tool_name") or "tool")
+            arguments = item.get("arguments")
             call_id = str(item.get("tool_call_id") or tracker.start(tool_name))
             response = await self._conn.request_permission(
                 options=[
@@ -484,10 +577,11 @@ class SuperQodeAcpAgent:
                 session_id=session.session_id,
                 tool_call=ToolCallUpdate(
                     tool_call_id=call_id,
-                    title=tool_name,
+                    title=_tool_title(tool_name, arguments),
                     kind=_tool_kind(tool_name),
                     status="pending",
-                    raw_input=item.get("arguments"),
+                    locations=_tool_locations(arguments),
+                    raw_input=arguments,
                 ),
             )
             outcome = getattr(response, "outcome", None)

{superqode-0.2.7 → superqode-0.2.8}/src/superqode/agent/loop.py

@@ -605,6 +605,11 @@ class AgentResponse:
     # and any schema-validation errors (empty list means valid).
     structured_output: Optional[Any] = None
     schema_errors: Optional[List[str]] = None
+    input_tokens: Optional[int] = None
+    output_tokens: Optional[int] = None
+    total_tokens: Optional[int] = None
+    cost_usd: Optional[float] = None
+    cost_currency: Optional[str] = None
 
 
 class ToolApprovalRequired(RuntimeError):
@@ -1991,8 +1996,60 @@ class AgentLoop:
         from .hooks import SESSION_START, STOP, USER_PROMPT_SUBMIT
 
         lifecycle_ctx = self._lifecycle_context()
+        usage_input_tokens = 0
+        usage_output_tokens = 0
+        usage_total_tokens = 0
+        usage_cost = 0.0
+        usage_seen = False
+        cost_seen = False
+        cost_currency = "USD"
+
+        def _record_gateway_usage(gateway_response) -> None:
+            nonlocal usage_input_tokens
+            nonlocal usage_output_tokens
+            nonlocal usage_total_tokens
+            nonlocal usage_cost
+            nonlocal usage_seen
+            nonlocal cost_seen
+            nonlocal cost_currency
+            usage = getattr(gateway_response, "usage", None)
+            if usage is not None:
+                prompt_tokens = int(getattr(usage, "prompt_tokens", 0) or 0)
+                completion_tokens = int(getattr(usage, "completion_tokens", 0) or 0)
+                total_tokens = int(getattr(usage, "total_tokens", 0) or 0)
+                if total_tokens <= 0:
+                    total_tokens = prompt_tokens + completion_tokens
+                usage_input_tokens += prompt_tokens
+                usage_output_tokens += completion_tokens
+                usage_total_tokens += total_tokens
+                usage_seen = True
+            cost = getattr(gateway_response, "cost", None)
+            if cost is not None:
+                input_cost = float(getattr(cost, "input_cost", 0.0) or 0.0)
+                output_cost = float(getattr(cost, "output_cost", 0.0) or 0.0)
+                total_cost = float(getattr(cost, "total_cost", 0.0) or 0.0)
+                if total_cost == 0.0 and (input_cost or output_cost):
+                    total_cost = input_cost + output_cost
+                usage_cost += total_cost
+                cost_currency = str(getattr(cost, "currency", None) or cost_currency or "USD")
+                cost_seen = True
 
         async def _finish(response: AgentResponse) -> AgentResponse:
+            if usage_seen:
+                response.input_tokens = (
+                    usage_input_tokens if response.input_tokens is None else response.input_tokens
+                )
+                response.output_tokens = (
+                    usage_output_tokens if response.output_tokens is None else response.output_tokens
+                )
+                response.total_tokens = (
+                    usage_total_tokens if response.total_tokens is None else response.total_tokens
+                )
+            if cost_seen:
+                response.cost_usd = usage_cost if response.cost_usd is None else response.cost_usd
+                response.cost_currency = (
+                    cost_currency if response.cost_currency is None else response.cost_currency
+                )
             self.run_active = False
             await self.hooks.fire(STOP, self._lifecycle_context(), response)
             # Opt-in automatic memory extraction, off the hot path.
@@ -2156,6 +2213,7 @@ class AgentLoop:
                         error=str(e),
                     )
                 )
+            _record_gateway_usage(response)
             await self.hooks.fire(AFTER_LLM_CALL, lifecycle_ctx, response)
 
             # Extract thinking content if available

{superqode-0.2.7 → superqode-0.2.8}/src/superqode/app/constants.py

@@ -371,6 +371,7 @@ COMMANDS = [
     ":serve web",
     ":serve harness",
     ":serve api",
+    ":serve acp",
     ":profiles",
     ":profiles list",
     ":doctor",
@@ -587,6 +588,18 @@ COMMANDS = [
     ":harness observability",
     ":harness observability status",
     ":harness observability export",
+    ":harness mine-failures",
+    ":harness logbook",
+    ":harness logbook update",
+    ":harness logbook show",
+    ":harness logbook export",
+    ":harness logbook prune",
+    ":harness audit-candidate",
+    ":harness candidates",
+    ":harness candidates list",
+    ":harness candidates show",
+    ":harness candidates export",
+    ":harness improve",
     ":harness optimize",
     ":harness optimize-inspect",
     ":harness optimize-ledger",

{superqode-0.2.7 → superqode-0.2.8}/src/superqode/app_main.py

@@ -11703,7 +11703,7 @@ class SuperQodeApp(App):
             self._show_harness_events(log, subargs)
             return
 
-        if sub in ("optimize", "optimize-inspect", "optimize-ledger"):
+        if sub in ("improve", "optimize", "optimize-inspect", "optimize-ledger"):
             try:
                 tokens = shlex.split(subargs or "")
             except ValueError as exc:
@@ -11714,16 +11714,22 @@ class SuperQodeApp(App):
                     "Usage: :harness optimize --spec <path> --tasks <path> [--export-only]"
                 )
                 return
+            if sub == "improve" and not tokens:
+                log.add_info(
+                    "Usage: :harness improve --spec <path> --tasks <path> [--from-failures failures.json] [--export-only]"
+                )
+                return
             if sub in {"optimize-inspect", "optimize-ledger"} and not tokens:
                 log.add_info(f"Usage: :harness {sub} <run_dir>")
                 return
-            self.run_worker(
-                self._superqode_cli_cmd(["harness", sub, *tokens], log, "Harness optimization")
-            )
+            label = "Harness self-improvement" if sub == "improve" else "Harness optimization"
+            self.run_worker(self._superqode_cli_cmd(["harness", sub, *tokens], log, label))
             return
 
         cli_backed_harness_subcommands = {
+            "audit-candidate",
             "auto-bench",
+            "candidates",
             "compile",
             "diff",
             "drain",
@@ -11734,6 +11740,8 @@ class SuperQodeApp(App):
             "import-omnigent",
             "inbox",
             "list-backends",
+            "logbook",
+            "mine-failures",
             "registry",
             "run",
             "test",
@@ -11767,7 +11775,7 @@ class SuperQodeApp(App):
 
         if not path:
             log.add_info(
-                "Usage: :harness <spec.yaml> | :harness wizard [name] --starter <template> --output <path> [--load] | :harness inspect | :harness doctor | :harness graph | :harness replay <run_id> | :harness fork <run_id> | :harness evidence <run_id> | :harness runs | :harness optimize --spec <path> --tasks <path> | :harness optimize-inspect <run_dir> | :harness optimize-ledger <run_dir> | :harness templates | :harness off"
+                "Usage: :harness <spec.yaml> | :harness wizard [name] --starter <template> --output <path> [--load] | :harness inspect | :harness doctor | :harness graph | :harness replay <run_id> | :harness fork <run_id> | :harness evidence <run_id> | :harness runs | :harness mine-failures --eval-result eval.json | :harness audit-candidate --base <path> --candidate <path> | :harness candidates list | :harness improve --spec <path> --tasks <path> | :harness optimize --spec <path> --tasks <path> | :harness optimize-inspect <run_dir> | :harness optimize-ledger <run_dir> | :harness templates | :harness off"
             )
             return
 
@@ -21415,6 +21423,7 @@ class SuperQodeApp(App):
             "shell": "▸",
             "terminal": "▸",
             "exec": "▸",
+            "run": "▸",
             "search": "⌕",
             "grep": "⌕",
             "find": "⌕",
@@ -21449,24 +21458,49 @@ class SuperQodeApp(App):
                 pass
             return p
 
+        def _first_arg(*keys: str) -> str:
+            for key in keys:
+                value = tool_input.get(key)
+                if isinstance(value, str) and value.strip():
+                    return value.strip()
+            return ""
+
+        # Cover snake_case and camelCase: harness tools, ACP agents, and the
+        # codex-sdk runtime all spell these keys differently.
         file_path = _relpath(
-            tool_input.get("filePath", tool_input.get("path", tool_input.get("file", "")))
+            _first_arg(
+                "filePath", "file_path", "path", "file", "abs_path", "filename", "target_file"
+            )
         )
 
-        if tool_lower in ("read", "write", "edit", "patch", "create") and file_path:
+        # Substring matching ("read_file", "Read file", "edit" all count as reads/
+        # edits); exact-name matching left every external agent in the generic branch.
+        def _matches(*fragments: str) -> bool:
+            return any(fragment in tool_lower for fragment in fragments)
+
+        if _matches("read", "write", "edit", "patch", "create") and file_path:
             return f"{icon} {file_path}"
-        if tool_lower in ("bash", "shell", "terminal", "exec"):
-            cmd = tool_input.get("command", "")
-            return f"{icon} {cmd}"
-        if tool_lower in ("search", "grep", "find"):
-            query = tool_input.get("pattern", tool_input.get("query", tool_input.get("search", "")))
-            return f"{icon} {query}"
-        if tool_lower in ("list", "ls", "glob"):
-            path = _relpath(tool_input.get("path", tool_input.get("directory", ".")))
-            return f"{icon} {path}"
+        if _matches("bash", "shell", "terminal", "exec", "command", "run"):
+            cmd = _first_arg("command", "cmd", "script")
+            if cmd:
+                return f"{icon} {cmd}"
+        if _matches("search", "grep", "find"):
+            query = _first_arg("pattern", "query", "search", "regex")
+            if query:
+                return f"{icon} {query}"
+        if _matches("list", "ls", "glob", "tree"):
+            path = _relpath(_first_arg("path", "directory", "dir_path"))
+            if path:
+                return f"{icon} {path}"
         if tool_lower == "todo_write":
             todos = tool_input.get("todos", [])
             return f"{icon} todo list ({len(todos)} items)"
+        if _matches("fetch", "web", "http"):
+            url = _first_arg("url", "uri")
+            if url:
+                return f"{icon} {url}"
+        if file_path:
+            return f"{icon} {tool_name} {file_path}"
 
         # Generic: show a short hint of the first argument value, not full JSON.
         if tool_input:
@@ -30202,6 +30236,26 @@ class SuperQodeApp(App):
                         "Show run evidence, changes, checks, and result receipt",
                     ),
                     (":harness events <run_id>", "Show persisted event timeline for a harness run"),
+                    (
+                        ":harness mine-failures --eval-result eval.json",
+                        "Mine structured self-improvement failures from harness JSON",
+                    ),
+                    (
+                        ":harness logbook show",
+                        "Show the file-backed self-improvement logbook",
+                    ),
+                    (
+                        ":harness audit-candidate --base <path> --candidate <path>",
+                        "Audit protected surfaces, eval gates, and reward-hacking risk",
+                    ),
+                    (
+                        ":harness candidates list",
+                        "Show accepted and rejected self-improvement candidates",
+                    ),
+                    (
+                        ":harness improve --spec <path> --tasks <path>",
+                        "Improve a HarnessSpec from mined failures and logbook memory",
+                    ),
                     (
                         ":harness optimize --spec <path> --tasks <path>",
                         "Optimize a HarnessSpec through optional metaharness",

{superqode-0.2.7 → superqode-0.2.8}/src/superqode/harness/__init__.py

@@ -41,6 +41,7 @@ from .spec import (
     HooksSpec,
     ModelPolicySpec,
     ObservabilitySpec,
+    OptimizationSpec,
     PermissionRuleSpec,
     RecursionSpec,
     RemoteHarnessSpec,
@@ -196,6 +197,8 @@ _LAZY_IMPORTS = {
     "HARNESS_DIMENSIONS": (".testing", "HARNESS_DIMENSIONS"),
     "dimension_for_category": (".testing", "dimension_for_category"),
     "eval_pack_path": (".eval", "eval_pack_path"),
+    "eval_task_split_counts": (".eval", "eval_task_split_counts"),
+    "filter_eval_tasks": (".eval", "filter_eval_tasks"),
     "list_eval_packs": (".eval", "list_eval_packs"),
     "load_eval_tasks": (".eval", "load_eval_tasks"),
     "run_harness_eval": (".eval", "run_harness_eval"),
@@ -212,6 +215,23 @@ _LAZY_IMPORTS = {
     "render_optimize_payload": (".optimize", "render_optimize_payload"),
     "render_metaharness_summary": (".optimize", "render_metaharness_summary"),
     "render_metaharness_ledger": (".optimize", "render_metaharness_ledger"),
+    "DEFAULT_LOGBOOK_DIR": (".self_improve", "DEFAULT_LOGBOOK_DIR"),
+    "DEFAULT_CANDIDATE_LEDGER_PATH": (".self_improve", "DEFAULT_CANDIDATE_LEDGER_PATH"),
+    "append_self_improve_evidence": (".self_improve", "append_self_improve_evidence"),
+    "audit_harness_candidate": (".self_improve", "audit_harness_candidate"),
+    "candidate_ledger_to_markdown": (".self_improve", "candidate_ledger_to_markdown"),
+    "logbook_to_markdown": (".self_improve", "logbook_to_markdown"),
+    "mine_harness_failures": (".self_improve", "mine_harness_failures"),
+    "prune_logbook": (".self_improve", "prune_logbook"),
+    "read_candidate_ledger": (".self_improve", "read_candidate_ledger"),
+    "read_logbook": (".self_improve", "read_logbook"),
+    "record_candidate_audit": (".self_improve", "record_candidate_audit"),
+    "render_candidate_audit": (".self_improve", "render_candidate_audit"),
+    "render_candidate_ledger": (".self_improve", "render_candidate_ledger"),
+    "render_failure_report": (".self_improve", "render_failure_report"),
+    "render_logbook": (".self_improve", "render_logbook"),
+    "update_logbook_from_failures": (".self_improve", "update_logbook_from_failures"),
+    "write_failure_report": (".self_improve", "write_failure_report"),
 }
 
 
@@ -240,6 +260,7 @@ __all__ = [
     "ModelPolicySpec",
     "PermissionRuleSpec",
     "ObservabilitySpec",
+    "OptimizationSpec",
     "RecursionSpec",
     "RemoteHarnessSpec",
     "RuntimeSpec",
@@ -387,6 +408,8 @@ __all__ = [
     "dimension_for_category",
     "harness_eval_regressions",
     "eval_pack_path",
+    "eval_task_split_counts",
+    "filter_eval_tasks",
     "list_eval_packs",
     "load_eval_tasks",
     "run_harness_eval",
@@ -402,6 +425,15 @@ __all__ = [
     "render_optimize_payload",
     "render_metaharness_summary",
     "render_metaharness_ledger",
+    "DEFAULT_LOGBOOK_DIR",
+    "append_self_improve_evidence",
+    "logbook_to_markdown",
+    "mine_harness_failures",
+    "read_logbook",
+    "render_failure_report",
+    "render_logbook",
+    "update_logbook_from_failures",
+    "write_failure_report",
     "omnigent_agent_to_harness_spec",
     "spec_from_headless_profile",
     # Performance