cawdex 1.35.75 → 1.35.77

package/resources/open_agent_leaderboard/cawdex-agent-card.md

@@ -1,119 +1,119 @@
----
-name: Cawdex
-version: 1.35.58
-developers:
-  - Crownelius
-license: MIT
-repository: https://github.com/Crownelius/cawdex
-framework: CLI agent with packaged benchmark adapters
-models:
-  - configurable OpenAI-compatible model
-tags:
-  - coding-agent
-  - general-agent
-  - open-agent-leaderboard
-  - exgentic
-  - terminal-bench
-  - kbench
-  - hal
-  - mempalace
----
-
-# Cawdex Agent Card
-
-## Agent Details
-
-Cawdex is a terminal coding agent system with a mind for the whole repo. It runs as a CLI, speaks OpenAI-compatible APIs, and packages adapters for Terminal-Bench, KBench, HAL, and Exgentic/Open Agent Leaderboard style evaluation. The npm package is `cawdex` and installs both the primary `cawdex` command and the legacy `cawdex` alias.
-
-This card documents the agent system. It is not an official benchmark result and does not claim leaderboard performance without official harness output.
-
-## Architecture
-
-Cawdex uses an iterative tool-calling loop with benchmark mode prompts, read-only preflight context, task-contract extraction, todo tracking, source-specific research, redacted benchmark traces, and structured process scoring.
-
-Primary tool surfaces include shell execution, file read/write/edit/patch operations, search/glob/listing, `benchmark_context`, `harness_components`, `research_sources`, `benchmark_repo_catalog`, `github_repo_digest`, `todo_write`, web fetch/search, MemPalace memory tools, and progressive-disclosure skills.
-
-Source-grounded benchmark work uses `research_sources` for current arXiv/GitHub/Hugging Face/Kaggle discovery and `benchmark_repo_catalog` as an offline Terminal-Bench public-repo seed, then `github_repo_digest` on relevant public repositories before adopting repo-level implementation patterns. The digest evidence is treated as a bounded demonstration to compare against local manifests, commands, CI files, and component surfaces, not as authority over the current checkout.
-
-Benchmark mode emphasizes:
-
-- Current task instructions and verifier output over prior memory.
-- Task-contract checklist creation before edits.
-- Task-alignment checks for ignored constraints, distractor/decoy references, and off-task-looking edits.
-- Reproduction before repair when feasible.
-- Live preflight checks for PATH, package-manager, interpreter, virtualenv, and network/offline mismatches before treating a verifier as representative.
-- Narrow-to-broad validation after edits.
-- Reward-hack checks for verifier tampering, oracle/solution probes, result-file edits, shortcut completion markers, and bypass commands.
-- CI workflow reconstruction from visible configuration.
-- Anti-leakage handling for oracle, answer, gold, hidden, result, and solution files.
-- Bounded replay of prior read/search/verifier checkpoints as hypotheses, not patch recipes.
-
-## Memory
-
-Cawdex includes MemPalace-backed project and global memory. In benchmark mode, `benchmark_context` can surface bounded relevant memories and prior local benchmark experience cards. These are explicitly framed as hypotheses that must be verified against current task files and verifier output. For Pi-Bench-style tasks, prior-run ranking uses complete proactivity ledgers as positive evidence and routes proactivity-ledger defects to warnings instead of replay hints.
-
-Benchmark traces write compact `experienceCard` summaries with replay checkpoints, failure signatures, component-observability edit classification, task-contract state and signals, task-alignment, spec-compliance, reward-hack, HarnessAudit-style harness-safety, long-horizon roadmap/SaaS/mobile/WebDevBench/SWE-Cycle/SWE-CI coverage risk signals, and Pi-Bench proactivity ledger signals for context contract, hidden-intent hypothesis, clarification, privacy, and observable completion evidence. They also capture environment-reconstruction setup/failure evidence, dependency-upgrade setup-validation evidence, root-cause hypothesis state, failure-onset diagnosis state, trajectory-triage categories for interaction/execution/environment informativeness, and targeted-fix counts for failed-verifier repair edits, decision-observability edit predictions, validation-reliability evidence, context-utilization precision/miss evidence plus pre-edit context-bloat evidence, trajectory-cleanup evidence for base64/data-URI blobs, high-entropy output, duplicate output, and excessive truncation, evidence-grounding signals for stale/no-effect edit retries without a current-state refresh, AHE publish-state mutation signals for post-pass edits or state-changing commands without revalidation, run-efficiency action/usage/cost/time evidence, source-research coverage, verification commands, changed files, and warnings. They also emit a redacted ACC-style task/context/answer JSONL artifact and an AHE-style change-evaluation artifact for edit prediction verdicts, unpredicted edits, targeted-fix counts, and post-edit regression-cycle attribution.
-
-## Models
-
-Cawdex classifies edit targets by changed surface and records explicit regression foresight for AHE-style component and decision observability. Non-trivial benchmark edits should name the component surface and include both `Prediction:` and `At-risk regression:` lines; failed-verifier repair edits should also record a `Root cause:`, `Diagnosis:`, or failure-tied `Hypothesis:` plus a `Targeted fix:` or `Fix plan:` before patching. Repeated failing-verifier reruns and post-edit regression cycles are compressed into a failure-onset diagnosis so repair loops can be inspected before another patch. Missing forecasts, diagnoses, failure-onset diagnoses, and fix plans appear in change evaluation, experience-card state, trajectory quality, process defects, and completion reminders.
-
-Cawdex is model-agnostic across OpenAI-compatible providers. Common configurations include OpenRouter, OpenAI, NVIDIA, Ollama, LM Studio, and DeepSeek-compatible endpoints. The model and provider are selected by CLI flags or environment configuration.
-
-## Supported Environments
-
-Packaged evaluation surfaces:
-
-- Terminal-Bench adapter.
-- KBench custom adapter.
-- HAL custom agent.
-- Exgentic/Open Agent Leaderboard custom agent.
-
-Benchmark mode is designed for SWE-bench-style code repair, Terminal-Bench and TerminalWorld-style terminal tasks, context-reuse benchmarks, long-horizon RoadmapBench/SaaSBench/SWE-Bench Mobile/SWE-WebDevBench/SWE-Cycle/SWE-CI-style tasks, SWE-PRBench-style pull request review tasks, TML-Bench/Kaggle-style tabular ML tasks, Pi-Bench-style proactive personal assistant tasks, Open Agent AppWorld/BrowseComp+/tau2-style tasks, and generic multi-step tool-use tasks. The TerminalWorld profile treats `instruction.md` or task text as the outcome contract, marks `solve.sh` as oracle-only reference material, and emphasizes real CLI execution plus persistent `/app` artifact/service verification for tasks synthesized from in-the-wild terminal recordings. The Exgentic adapter builds a deterministic recommended action shortlist from the current task, context, latest observation, profile, schemas, and recent diagnostics before showing the full action schemas, highlights required argument keys with redacted exact current-state hints when available, repairs case/camelCase/schema-key near misses and exact latest-observation/context required-argument omissions before `ActionType` dispatch, avoids repeating no-effect actions when the latest observation did not change, uses the shortlist/hints to recover from malformed or missing action JSON with a viable non-finish action while completion is not ready, then folds prior observations/actions into a compact task-relevant ledger between steps so long noisy sessions keep current state, policy evidence, TerminalWorld artifact requirements and reference-solution avoidance, WebDevBench canary requirements, frontend/backend evidence, SWE-Cycle lifecycle phases, environment setup state, generated/selected tests, judge evidence, SWE-CI current/target commits, test gaps, inferred requirements, verifier deltas, SWE-PRBench PR metadata/diff/findings/evidence gaps, TML-Bench data contract/validation/submission evidence, Pi-Bench user/workspace/app context, hidden-intent hypotheses, clarification state, privacy risk, selected actions, and diagnostics in view without repeatedly reinjecting raw transcripts. The interactive CLI acknowledges submitted turns before provider I/O, treats F5/Shift+F5 raw terminal sequences as active-turn cancellation on Windows/xterm terminals, and auto-heals known-stuck OpenRouter preview models to the configured free fallback unless explicitly overridden.
-
-## Evaluation Results
-
-Cawdex writes `summary.json`, `trace.jsonl`, `worktree.patch`, `git-status.txt`, `open-agent-leaderboard-draft.json`, `agent-context-compiled.jsonl`, `change-evaluation.json`, and `submission-bundle-manifest.json` artifacts when benchmark trace output is enabled. The draft row follows the public Open Agent Leaderboard result-column shape where local trace evidence can support it, but remains `submissionReady:false` until an official harness supplies benchmark-owned scores and session success evidence. The submission bundle manifest indexes artifact paths and SHA-256 hashes, summarizes verifier/usage/process evidence, and lists missing official fields so local traces are not mistaken for leaderboard scores. Trajectory quality includes explicit task-alignment, spec-compliance, reward-hack, HarnessAudit-style harness-safety, long-horizon coverage, Pi-Bench proactivity, component-observability, root-cause hypothesis, failure-onset diagnosis, trajectory triage, targeted-fix manifest, context-utilization, candidate-file dossier, trajectory cleanup, pre-edit context-bloat, weak change-manifest, and evidence-grounding risk fields so benchmark reviewers can separate genuine task progress from distractor-following, repair edits without a failure-tied diagnosis or fix plan, undiagnosed verifier repair loops, recall-heavy unused context gathering without a compact localization dossier, noisy encoded or duplicate tool observations, visible-suite-only validation, stale/no-effect edit loops, verifier tampering, unsafe protected-resource access, external information transfer, destructive operations, oracle access, shortcut score markers, unsupported RoadmapBench/SaaSBench/SWE-Bench Mobile/SWE-WebDevBench/SWE-Cycle/SWE-CI/Pi-Bench completion claims, or edits/actions without falsifiable prediction and observable follow-through.
-
-Prior experience reuse also reads AHE change-evaluation verdicts. Confirmed manifests can rank higher, while contradicted, regression-risk, pending-verification, missing-prediction, or missing-regression-forecast manifests are emitted as warning patterns instead of replay hints.
-
-Prior experience reuse also applies ContextBench-style context discipline: concise runs whose inspected files were used by the eventual patch can rank higher, while low-utilization or pre-edit context-bloat runs are emitted as warning patterns instead of replay hints.
-
-Prior experience reuse also applies AHE-style cleanup discipline: traces with encoded blobs, duplicate observations, or excessive truncation are emitted as warning patterns instead of replay hints.
-
-Prior experience reuse also applies AHE-style diagnosis discipline: traces that repaired after a failed verifier without a root-cause hypothesis are emitted as warning patterns instead of replay hints.
-
-Prior experience reuse also applies failure-onset discipline: traces with repeated verifier loops or regression cycles that were repaired without a diagnosis are emitted as warning patterns instead of replay hints.
-
-Prior experience reuse also applies AHE-style fix-plan discipline: traces that repaired after a failed verifier without a targeted-fix manifest are emitted as warning patterns instead of replay hints.
-
-Interactive type-ahead is preserved through active-turn cancellation and permission interruptions: text captured while the model/tool chain is running is restored into the next editable prompt instead of being emitted as a passive queued hint or silently submitted.
-
-Official results should be produced through Exgentic, HAL, Terminal-Bench, KBench, or another benchmark-owned grader before submission.
-
-## Limitations
-
-- Prior memory and replay traces can be stale or mismatched; current task evidence must override them.
-- Generic web or source research cannot prove task success without local or official verifier evidence.
-- The agent card does not substitute for official harness scoring.
-- Hosted or sandboxed benchmarks may restrict network, package install, or provider access; use pinned bundles or preinstalled `cawdex` where possible. The legacy `cawdex` alias remains supported for older images.
-- Open-weight or free-tier models may show high variance on long-horizon tasks.
-
-## How To Run
-
-Print packaged adapters and card paths:
-
-```bash
-cawdex --print-exgentic-agent
-cawdex --print-hal-agent
-cawdex --print-kbench-adapter
-cawdex --print-open-agent-card
-```
-
-Run a benchmark task directly:
-
-```bash
-cawdex --provider openrouter --model openrouter/free --perm yolo --prompt "/benchmark swe-bench fix the issue"
-```
-
-For reproducible leaderboard runs, pin the installed package or bundle, pass provider credentials through environment variables, enable benchmark trace output, and submit only official harness results.
+---
+name: Cawdex
+version: 1.35.58
+developers:
+  - Crownelius
+license: MIT
+repository: https://github.com/Crownelius/cawdex
+framework: CLI agent with packaged benchmark adapters
+models:
+  - configurable OpenAI-compatible model
+tags:
+  - coding-agent
+  - general-agent
+  - open-agent-leaderboard
+  - exgentic
+  - terminal-bench
+  - kbench
+  - hal
+  - mempalace
+---
+
+# Cawdex Agent Card
+
+## Agent Details
+
+Cawdex is a terminal coding agent system with a mind for the whole repo. It runs as a CLI, speaks OpenAI-compatible APIs, and packages adapters for Terminal-Bench, KBench, HAL, and Exgentic/Open Agent Leaderboard style evaluation. The npm package is `cawdex` and installs both the primary `cawdex` command and the legacy `cawdex` alias.
+
+This card documents the agent system. It is not an official benchmark result and does not claim leaderboard performance without official harness output.
+
+## Architecture
+
+Cawdex uses an iterative tool-calling loop with benchmark mode prompts, read-only preflight context, task-contract extraction, todo tracking, source-specific research, redacted benchmark traces, and structured process scoring.
+
+Primary tool surfaces include shell execution, file read/write/edit/patch operations, search/glob/listing, `benchmark_context`, `harness_components`, `research_sources`, `benchmark_repo_catalog`, `github_repo_digest`, `todo_write`, web fetch/search, MemPalace memory tools, and progressive-disclosure skills.
+
+Source-grounded benchmark work uses `research_sources` for current arXiv/GitHub/Hugging Face/Kaggle discovery and `benchmark_repo_catalog` as an offline Terminal-Bench public-repo seed, then `github_repo_digest` on relevant public repositories before adopting repo-level implementation patterns. The digest evidence is treated as a bounded demonstration to compare against local manifests, commands, CI files, and component surfaces, not as authority over the current checkout.
+
+Benchmark mode emphasizes:
+
+- Current task instructions and verifier output over prior memory.
+- Task-contract checklist creation before edits.
+- Task-alignment checks for ignored constraints, distractor/decoy references, and off-task-looking edits.
+- Reproduction before repair when feasible.
+- Live preflight checks for PATH, package-manager, interpreter, virtualenv, and network/offline mismatches before treating a verifier as representative.
+- Narrow-to-broad validation after edits.
+- Reward-hack checks for verifier tampering, oracle/solution probes, result-file edits, shortcut completion markers, and bypass commands.
+- CI workflow reconstruction from visible configuration.
+- Anti-leakage handling for oracle, answer, gold, hidden, result, and solution files.
+- Bounded replay of prior read/search/verifier checkpoints as hypotheses, not patch recipes.
+
+## Memory
+
+Cawdex includes MemPalace-backed project and global memory. In benchmark mode, `benchmark_context` can surface bounded relevant memories and prior local benchmark experience cards. These are explicitly framed as hypotheses that must be verified against current task files and verifier output. For Pi-Bench-style tasks, prior-run ranking uses complete proactivity ledgers as positive evidence and routes proactivity-ledger defects to warnings instead of replay hints.
+
+Benchmark traces write compact `experienceCard` summaries with replay checkpoints, failure signatures, component-observability edit classification, task-contract state and signals, task-alignment, spec-compliance, reward-hack, HarnessAudit-style harness-safety, long-horizon roadmap/SaaS/mobile/WebDevBench/SWE-Cycle/SWE-CI coverage risk signals, and Pi-Bench proactivity ledger signals for context contract, hidden-intent hypothesis, clarification, privacy, and observable completion evidence. They also capture environment-reconstruction setup/failure evidence, dependency-upgrade setup-validation evidence, root-cause hypothesis state, failure-onset diagnosis state, trajectory-triage categories for interaction/execution/environment informativeness, and targeted-fix counts for failed-verifier repair edits, decision-observability edit predictions, validation-reliability evidence, context-utilization precision/miss evidence plus pre-edit context-bloat evidence, trajectory-cleanup evidence for base64/data-URI blobs, high-entropy output, duplicate output, and excessive truncation, evidence-grounding signals for stale/no-effect edit retries without a current-state refresh, AHE publish-state mutation signals for post-pass edits or state-changing commands without revalidation, run-efficiency action/usage/cost/time evidence, source-research coverage, verification commands, changed files, and warnings. They also emit a redacted ACC-style task/context/answer JSONL artifact and an AHE-style change-evaluation artifact for edit prediction verdicts, unpredicted edits, targeted-fix counts, and post-edit regression-cycle attribution.
+
+## Models
+
+Cawdex classifies edit targets by changed surface and records explicit regression foresight for AHE-style component and decision observability. Non-trivial benchmark edits should name the component surface and include both `Prediction:` and `At-risk regression:` lines; failed-verifier repair edits should also record a `Root cause:`, `Diagnosis:`, or failure-tied `Hypothesis:` plus a `Targeted fix:` or `Fix plan:` before patching. Repeated failing-verifier reruns and post-edit regression cycles are compressed into a failure-onset diagnosis so repair loops can be inspected before another patch. Missing forecasts, diagnoses, failure-onset diagnoses, and fix plans appear in change evaluation, experience-card state, trajectory quality, process defects, and completion reminders.
+
+Cawdex is model-agnostic across OpenAI-compatible providers. Common configurations include OpenRouter, OpenAI, NVIDIA, Ollama, LM Studio, and DeepSeek-compatible endpoints. The model and provider are selected by CLI flags or environment configuration.
+
+## Supported Environments
+
+Packaged evaluation surfaces:
+
+- Terminal-Bench adapter.
+- KBench custom adapter.
+- HAL custom agent.
+- Exgentic/Open Agent Leaderboard custom agent.
+
+Benchmark mode is designed for SWE-bench-style code repair, Terminal-Bench and TerminalWorld-style terminal tasks, context-reuse benchmarks, long-horizon RoadmapBench/SaaSBench/SWE-Bench Mobile/SWE-WebDevBench/SWE-Cycle/SWE-CI-style tasks, SWE-PRBench-style pull request review tasks, TML-Bench/Kaggle-style tabular ML tasks, Pi-Bench-style proactive personal assistant tasks, Open Agent AppWorld/BrowseComp+/tau2-style tasks, and generic multi-step tool-use tasks. The TerminalWorld profile treats `instruction.md` or task text as the outcome contract, marks `solve.sh` as oracle-only reference material, and emphasizes real CLI execution plus persistent `/app` artifact/service verification for tasks synthesized from in-the-wild terminal recordings. The Exgentic adapter builds a deterministic recommended action shortlist from the current task, context, latest observation, profile, schemas, and recent diagnostics before showing the full action schemas, highlights required argument keys with redacted exact current-state hints when available, repairs case/camelCase/schema-key near misses and exact latest-observation/context required-argument omissions before `ActionType` dispatch, avoids repeating no-effect actions when the latest observation did not change, uses the shortlist/hints to recover from malformed or missing action JSON with a viable non-finish action while completion is not ready, then folds prior observations/actions into a compact task-relevant ledger between steps so long noisy sessions keep current state, policy evidence, TerminalWorld artifact requirements and reference-solution avoidance, WebDevBench canary requirements, frontend/backend evidence, SWE-Cycle lifecycle phases, environment setup state, generated/selected tests, judge evidence, SWE-CI current/target commits, test gaps, inferred requirements, verifier deltas, SWE-PRBench PR metadata/diff/findings/evidence gaps, TML-Bench data contract/validation/submission evidence, Pi-Bench user/workspace/app context, hidden-intent hypotheses, clarification state, privacy risk, selected actions, and diagnostics in view without repeatedly reinjecting raw transcripts. The interactive CLI acknowledges submitted turns before provider I/O, treats F5/Shift+F5 raw terminal sequences as active-turn cancellation on Windows/xterm terminals, and auto-heals known-stuck OpenRouter preview models to the configured free fallback unless explicitly overridden.
+
+## Evaluation Results
+
+Cawdex writes `summary.json`, `trace.jsonl`, `worktree.patch`, `git-status.txt`, `open-agent-leaderboard-draft.json`, `agent-context-compiled.jsonl`, `change-evaluation.json`, and `submission-bundle-manifest.json` artifacts when benchmark trace output is enabled. The draft row follows the public Open Agent Leaderboard result-column shape where local trace evidence can support it, but remains `submissionReady:false` until an official harness supplies benchmark-owned scores and session success evidence. The submission bundle manifest indexes artifact paths and SHA-256 hashes, summarizes verifier/usage/process evidence, and lists missing official fields so local traces are not mistaken for leaderboard scores. Trajectory quality includes explicit task-alignment, spec-compliance, reward-hack, HarnessAudit-style harness-safety, long-horizon coverage, Pi-Bench proactivity, component-observability, root-cause hypothesis, failure-onset diagnosis, trajectory triage, targeted-fix manifest, context-utilization, candidate-file dossier, trajectory cleanup, pre-edit context-bloat, weak change-manifest, and evidence-grounding risk fields so benchmark reviewers can separate genuine task progress from distractor-following, repair edits without a failure-tied diagnosis or fix plan, undiagnosed verifier repair loops, recall-heavy unused context gathering without a compact localization dossier, noisy encoded or duplicate tool observations, visible-suite-only validation, stale/no-effect edit loops, verifier tampering, unsafe protected-resource access, external information transfer, destructive operations, oracle access, shortcut score markers, unsupported RoadmapBench/SaaSBench/SWE-Bench Mobile/SWE-WebDevBench/SWE-Cycle/SWE-CI/Pi-Bench completion claims, or edits/actions without falsifiable prediction and observable follow-through.
+
+Prior experience reuse also reads AHE change-evaluation verdicts. Confirmed manifests can rank higher, while contradicted, regression-risk, pending-verification, missing-prediction, or missing-regression-forecast manifests are emitted as warning patterns instead of replay hints.
+
+Prior experience reuse also applies ContextBench-style context discipline: concise runs whose inspected files were used by the eventual patch can rank higher, while low-utilization or pre-edit context-bloat runs are emitted as warning patterns instead of replay hints.
+
+Prior experience reuse also applies AHE-style cleanup discipline: traces with encoded blobs, duplicate observations, or excessive truncation are emitted as warning patterns instead of replay hints.
+
+Prior experience reuse also applies AHE-style diagnosis discipline: traces that repaired after a failed verifier without a root-cause hypothesis are emitted as warning patterns instead of replay hints.
+
+Prior experience reuse also applies failure-onset discipline: traces with repeated verifier loops or regression cycles that were repaired without a diagnosis are emitted as warning patterns instead of replay hints.
+
+Prior experience reuse also applies AHE-style fix-plan discipline: traces that repaired after a failed verifier without a targeted-fix manifest are emitted as warning patterns instead of replay hints.
+
+Interactive type-ahead is preserved through active-turn cancellation and permission interruptions: text captured while the model/tool chain is running is restored into the next editable prompt instead of being emitted as a passive queued hint or silently submitted.
+
+Official results should be produced through Exgentic, HAL, Terminal-Bench, KBench, or another benchmark-owned grader before submission.
+
+## Limitations
+
+- Prior memory and replay traces can be stale or mismatched; current task evidence must override them.
+- Generic web or source research cannot prove task success without local or official verifier evidence.
+- The agent card does not substitute for official harness scoring.
+- Hosted or sandboxed benchmarks may restrict network, package install, or provider access; use pinned bundles or preinstalled `cawdex` where possible. The legacy `cawdex` alias remains supported for older images.
+- Open-weight or free-tier models may show high variance on long-horizon tasks.
+
+## How To Run
+
+Print packaged adapters and card paths:
+
+```bash
+cawdex --print-exgentic-agent
+cawdex --print-hal-agent
+cawdex --print-kbench-adapter
+cawdex --print-open-agent-card
+```
+
+Run a benchmark task directly:
+
+```bash
+cawdex --provider openrouter --model openrouter/free --perm yolo --prompt "/benchmark swe-bench fix the issue"
+```
+
+For reproducible leaderboard runs, pin the installed package or bundle, pass provider credentials through environment variables, enable benchmark trace output, and submit only official harness results.

package/resources/terminal_bench/__init__.py

@@ -1 +1 @@
-"""cawdex Terminal-Bench adapter package."""
+"""cawdex Terminal-Bench adapter package."""

package/resources/terminal_bench/cawdex_agent.py

@@ -1,174 +1,174 @@
-"""Terminal-Bench adapter for Cawdex.
-
-Usage:
-    tb run --agent-import-path resources.terminal_bench.cawdex_agent:CawdexTerminalBenchAgent ...
-
-The adapter installs the npm package in the task container, then runs
-Cawdex in non-interactive benchmark mode with the task instruction.
-"""
-
-from __future__ import annotations
-
-import os
-import shlex
-from pathlib import Path
-
-from terminal_bench.agents.installed_agents.abstract_installed_agent import (
-    AbstractInstalledAgent,
-)
-
-try:
-    from terminal_bench.harness_models import TerminalCommand
-except ImportError:  # terminal-bench moved this in newer releases
-    from terminal_bench.terminal.models import TerminalCommand
-
-
-class CawdexTerminalBenchAgent(AbstractInstalledAgent):
-    """Terminal-Bench agent for Cawdex."""
-
-    @staticmethod
-    def name() -> str:
-        return "cawdex"
-
-    def __init__(
-        self,
-        model_name: str | None = None,
-        provider: str | None = None,
-        install_spec: str | None = None,
-        max_turns: int | None = None,
-        *args,
-        **kwargs,
-    ):
-        super().__init__(*args, **kwargs)
-        self._model_name = model_name
-        self._provider = provider
-        self._install_spec = install_spec
-        self._max_turns = max_turns
-
-    @property
-    def _env(self) -> dict[str, str]:
-        env: dict[str, str] = {
-            "CAWDEX_ENV_CONFIG": "1",
-            "CAWDEX_HOME": "/tmp/cawdex-home",
-            "CAWDEX_THEME": "minimal",
-            "CAWDEX_SHOW_THINKING": "0",
-            "CAWDEX_MEMORY": os.environ.get("CAWDEX_MEMORY", "0"),
-            "CAWDEX_BASH_TIMEOUT_MS": os.environ.get("CAWDEX_BASH_TIMEOUT_MS", "300000"),
-            "CAWDEX_INSTALL_SPEC": self._install_spec
-            or os.environ.get("CAWDEX_INSTALL_SPEC", "cawdex@latest"),
-        }
-
-        passthrough = [
-            "CAWDEX_API_KEY",
-            "CAWDEX_BASE_URL",
-            "CAWDEX_MODEL",
-            "CAWDEX_FALLBACK_MODEL",
-            "CAWDEX_MAX_TOKENS",
-            "CAWDEX_CONTEXT_WINDOW_TOKENS",
-            "CAWDEX_COMPACTION_TRIGGER_TOKENS",
-            "CAWDEX_COMPACTION_MODEL",
-            "CAWDEX_COMPACTION_MAX_TOKENS",
-            "CAWDEX_COMPACTION_USE_FALLBACK",
-            "CAWDEX_LLM_COMPACTION",
-            "CAWDEX_COMPACTION_MODE",
-            "CAWDEX_LOCAL_COMPACTION_FALLBACK",
-            "CAWDEX_TEMPERATURE",
-            "CAWDEX_BUNDLE_ROOT",
-            "CAWDEX_BUNDLE_TARBALL",
-            "OPENROUTER_API_KEY",
-            "OPENAI_API_KEY",
-            "DEEPSEEK_API_KEY",
-            "NVIDIA_API_KEY",
-            "GOOGLE_API_KEY",
-            "GEMINI_API_KEY",
-            "GLM_API_KEY",
-            "ZHIPUAI_API_KEY",
-        ]
-        for key in passthrough:
-            if os.environ.get(key):
-                env[key] = os.environ[key]
-
-        if self._provider:
-            env["CAWDEX_PROVIDER"] = self._provider
-        elif os.environ.get("CAWDEX_PROVIDER"):
-            env["CAWDEX_PROVIDER"] = os.environ["CAWDEX_PROVIDER"]
-
-        if self._model_name:
-            env["CAWDEX_MODEL"] = self._model_name
-        if self._max_turns:
-            env["CAWDEX_MAX_TURNS"] = str(self._max_turns)
-        elif os.environ.get("CAWDEX_MAX_TURNS"):
-            env["CAWDEX_MAX_TURNS"] = os.environ["CAWDEX_MAX_TURNS"]
-
-        return env
-
-    @property
-    def _install_agent_script_path(self) -> Path:
-        return Path(__file__).parent / "setup.sh"
-
-    def _run_agent_commands(self, task_description: str) -> list[TerminalCommand]:
-        instruction = "/benchmark terminal-bench " + task_description
-        agent_command = (
-            "cawdex "
-            f"--prompt {shlex.quote(instruction)} "
-            "--perm yolo "
-            "--benchmark-trace-dir .cawdex/trace"
-        )
-        script = (
-            f"{agent_command}; "
-            "status=$?; "
-            "mkdir -p .cawdex; "
-            "redact_cawdex_artifact() { "
-            "sed -E "
-            "-e 's/sk-or-v1-[A-Za-z0-9_-]+/sk-or-v1-[REDACTED]/g' "
-            "-e 's/sk-[A-Za-z0-9_-]{16,}/sk-[REDACTED]/g' "
-            "-e 's/hf_[A-Za-z0-9]{16,}/hf_[REDACTED]/g' "
-            "-e 's/KGAT_[A-Za-z0-9]{16,}/KGAT_[REDACTED]/g' "
-            "-e 's/npm_[A-Za-z0-9]{16,}/npm_[REDACTED]/g'; "
-            "}; "
-            "summary=$(find .cawdex/trace -name summary.json -type f 2>/dev/null | sort | tail -n 1 || true); "
-            "if [ -n \"$summary\" ] && [ -f \"$summary\" ]; then "
-            "cp \"$summary\" .cawdex/benchmark-summary.json; "
-            "trace_dir=$(dirname \"$summary\"); "
-            "if [ -f \"$trace_dir/trace.jsonl\" ]; then cp \"$trace_dir/trace.jsonl\" .cawdex/benchmark-trace.jsonl; fi; "
-            "if [ -f \"$trace_dir/agent-context-compiled.jsonl\" ]; then cp \"$trace_dir/agent-context-compiled.jsonl\" .cawdex/agent-context-compiled.jsonl; fi; "
-            "if [ -f \"$trace_dir/change-evaluation.json\" ]; then cp \"$trace_dir/change-evaluation.json\" .cawdex/change-evaluation.json; fi; "
-            "if [ -f \"$trace_dir/submission-bundle-manifest.json\" ]; then cp \"$trace_dir/submission-bundle-manifest.json\" .cawdex/submission-bundle-manifest.json; fi; "
-            "fi; "
-            "if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then "
-            "{ git diff --binary --no-ext-diff 2>/dev/null || true; "
-            "git diff --cached --binary --no-ext-diff 2>/dev/null || true; "
-            "git ls-files --others --exclude-standard -z 2>/dev/null | "
-            "while IFS= read -r -d '' f; do "
-            "git diff --no-index --binary --no-ext-diff -- /dev/null \"$f\" 2>/dev/null || true; "
-            "done; } | redact_cawdex_artifact > .cawdex/benchmark.patch; "
-            "git status --short 2>/dev/null | redact_cawdex_artifact > .cawdex/git-status.txt || true; "
-            "fi; "
-            "if [ -s .cawdex/benchmark.patch ]; then "
-            "echo '[cawdex] patch artifact: .cawdex/benchmark.patch'; "
-            "fi; "
-            "if [ -s .cawdex/benchmark-summary.json ]; then "
-            "echo '[cawdex] trace summary: .cawdex/benchmark-summary.json'; "
-            "fi; "
-            "if [ -s .cawdex/benchmark-trace.jsonl ]; then "
-            "echo '[cawdex] tool trace: .cawdex/benchmark-trace.jsonl'; "
-            "fi; "
-            "if [ -s .cawdex/agent-context-compiled.jsonl ]; then "
-            "echo '[cawdex] context compilation: .cawdex/agent-context-compiled.jsonl'; "
-            "fi; "
-            "if [ -s .cawdex/change-evaluation.json ]; then "
-            "echo '[cawdex] change evaluation: .cawdex/change-evaluation.json'; "
-            "fi; "
-            "if [ -s .cawdex/submission-bundle-manifest.json ]; then "
-            "echo '[cawdex] submission bundle: .cawdex/submission-bundle-manifest.json'; "
-            "fi; "
-            "exit \"$status\""
-        )
-        command = "bash -lc " + shlex.quote(script)
-        return [
-            TerminalCommand(
-                command=command,
-                max_timeout_sec=float("inf"),
-                block=True,
-            )
-        ]
+"""Terminal-Bench adapter for Cawdex.
+
+Usage:
+    tb run --agent-import-path resources.terminal_bench.cawdex_agent:CawdexTerminalBenchAgent ...
+
+The adapter installs the npm package in the task container, then runs
+Cawdex in non-interactive benchmark mode with the task instruction.
+"""
+
+from __future__ import annotations
+
+import os
+import shlex
+from pathlib import Path
+
+from terminal_bench.agents.installed_agents.abstract_installed_agent import (
+    AbstractInstalledAgent,
+)
+
+try:
+    from terminal_bench.harness_models import TerminalCommand
+except ImportError:  # terminal-bench moved this in newer releases
+    from terminal_bench.terminal.models import TerminalCommand
+
+
+class CawdexTerminalBenchAgent(AbstractInstalledAgent):
+    """Terminal-Bench agent for Cawdex."""
+
+    @staticmethod
+    def name() -> str:
+        return "cawdex"
+
+    def __init__(
+        self,
+        model_name: str | None = None,
+        provider: str | None = None,
+        install_spec: str | None = None,
+        max_turns: int | None = None,
+        *args,
+        **kwargs,
+    ):
+        super().__init__(*args, **kwargs)
+        self._model_name = model_name
+        self._provider = provider
+        self._install_spec = install_spec
+        self._max_turns = max_turns
+
+    @property
+    def _env(self) -> dict[str, str]:
+        env: dict[str, str] = {
+            "CAWDEX_ENV_CONFIG": "1",
+            "CAWDEX_HOME": "/tmp/cawdex-home",
+            "CAWDEX_THEME": "minimal",
+            "CAWDEX_SHOW_THINKING": "0",
+            "CAWDEX_MEMORY": os.environ.get("CAWDEX_MEMORY", "0"),
+            "CAWDEX_BASH_TIMEOUT_MS": os.environ.get("CAWDEX_BASH_TIMEOUT_MS", "300000"),
+            "CAWDEX_INSTALL_SPEC": self._install_spec
+            or os.environ.get("CAWDEX_INSTALL_SPEC", "cawdex@latest"),
+        }
+
+        passthrough = [
+            "CAWDEX_API_KEY",
+            "CAWDEX_BASE_URL",
+            "CAWDEX_MODEL",
+            "CAWDEX_FALLBACK_MODEL",
+            "CAWDEX_MAX_TOKENS",
+            "CAWDEX_CONTEXT_WINDOW_TOKENS",
+            "CAWDEX_COMPACTION_TRIGGER_TOKENS",
+            "CAWDEX_COMPACTION_MODEL",
+            "CAWDEX_COMPACTION_MAX_TOKENS",
+            "CAWDEX_COMPACTION_USE_FALLBACK",
+            "CAWDEX_LLM_COMPACTION",
+            "CAWDEX_COMPACTION_MODE",
+            "CAWDEX_LOCAL_COMPACTION_FALLBACK",
+            "CAWDEX_TEMPERATURE",
+            "CAWDEX_BUNDLE_ROOT",
+            "CAWDEX_BUNDLE_TARBALL",
+            "OPENROUTER_API_KEY",
+            "OPENAI_API_KEY",
+            "DEEPSEEK_API_KEY",
+            "NVIDIA_API_KEY",
+            "GOOGLE_API_KEY",
+            "GEMINI_API_KEY",
+            "GLM_API_KEY",
+            "ZHIPUAI_API_KEY",
+        ]
+        for key in passthrough:
+            if os.environ.get(key):
+                env[key] = os.environ[key]
+
+        if self._provider:
+            env["CAWDEX_PROVIDER"] = self._provider
+        elif os.environ.get("CAWDEX_PROVIDER"):
+            env["CAWDEX_PROVIDER"] = os.environ["CAWDEX_PROVIDER"]
+
+        if self._model_name:
+            env["CAWDEX_MODEL"] = self._model_name
+        if self._max_turns:
+            env["CAWDEX_MAX_TURNS"] = str(self._max_turns)
+        elif os.environ.get("CAWDEX_MAX_TURNS"):
+            env["CAWDEX_MAX_TURNS"] = os.environ["CAWDEX_MAX_TURNS"]
+
+        return env
+
+    @property
+    def _install_agent_script_path(self) -> Path:
+        return Path(__file__).parent / "setup.sh"
+
+    def _run_agent_commands(self, task_description: str) -> list[TerminalCommand]:
+        instruction = "/benchmark terminal-bench " + task_description
+        agent_command = (
+            "cawdex "
+            f"--prompt {shlex.quote(instruction)} "
+            "--perm yolo "
+            "--benchmark-trace-dir .cawdex/trace"
+        )
+        script = (
+            f"{agent_command}; "
+            "status=$?; "
+            "mkdir -p .cawdex; "
+            "redact_cawdex_artifact() { "
+            "sed -E "
+            "-e 's/sk-or-v1-[A-Za-z0-9_-]+/sk-or-v1-[REDACTED]/g' "
+            "-e 's/sk-[A-Za-z0-9_-]{16,}/sk-[REDACTED]/g' "
+            "-e 's/hf_[A-Za-z0-9]{16,}/hf_[REDACTED]/g' "
+            "-e 's/KGAT_[A-Za-z0-9]{16,}/KGAT_[REDACTED]/g' "
+            "-e 's/npm_[A-Za-z0-9]{16,}/npm_[REDACTED]/g'; "
+            "}; "
+            "summary=$(find .cawdex/trace -name summary.json -type f 2>/dev/null | sort | tail -n 1 || true); "
+            "if [ -n \"$summary\" ] && [ -f \"$summary\" ]; then "
+            "cp \"$summary\" .cawdex/benchmark-summary.json; "
+            "trace_dir=$(dirname \"$summary\"); "
+            "if [ -f \"$trace_dir/trace.jsonl\" ]; then cp \"$trace_dir/trace.jsonl\" .cawdex/benchmark-trace.jsonl; fi; "
+            "if [ -f \"$trace_dir/agent-context-compiled.jsonl\" ]; then cp \"$trace_dir/agent-context-compiled.jsonl\" .cawdex/agent-context-compiled.jsonl; fi; "
+            "if [ -f \"$trace_dir/change-evaluation.json\" ]; then cp \"$trace_dir/change-evaluation.json\" .cawdex/change-evaluation.json; fi; "
+            "if [ -f \"$trace_dir/submission-bundle-manifest.json\" ]; then cp \"$trace_dir/submission-bundle-manifest.json\" .cawdex/submission-bundle-manifest.json; fi; "
+            "fi; "
+            "if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then "
+            "{ git diff --binary --no-ext-diff 2>/dev/null || true; "
+            "git diff --cached --binary --no-ext-diff 2>/dev/null || true; "
+            "git ls-files --others --exclude-standard -z 2>/dev/null | "
+            "while IFS= read -r -d '' f; do "
+            "git diff --no-index --binary --no-ext-diff -- /dev/null \"$f\" 2>/dev/null || true; "
+            "done; } | redact_cawdex_artifact > .cawdex/benchmark.patch; "
+            "git status --short 2>/dev/null | redact_cawdex_artifact > .cawdex/git-status.txt || true; "
+            "fi; "
+            "if [ -s .cawdex/benchmark.patch ]; then "
+            "echo '[cawdex] patch artifact: .cawdex/benchmark.patch'; "
+            "fi; "
+            "if [ -s .cawdex/benchmark-summary.json ]; then "
+            "echo '[cawdex] trace summary: .cawdex/benchmark-summary.json'; "
+            "fi; "
+            "if [ -s .cawdex/benchmark-trace.jsonl ]; then "
+            "echo '[cawdex] tool trace: .cawdex/benchmark-trace.jsonl'; "
+            "fi; "
+            "if [ -s .cawdex/agent-context-compiled.jsonl ]; then "
+            "echo '[cawdex] context compilation: .cawdex/agent-context-compiled.jsonl'; "
+            "fi; "
+            "if [ -s .cawdex/change-evaluation.json ]; then "
+            "echo '[cawdex] change evaluation: .cawdex/change-evaluation.json'; "
+            "fi; "
+            "if [ -s .cawdex/submission-bundle-manifest.json ]; then "
+            "echo '[cawdex] submission bundle: .cawdex/submission-bundle-manifest.json'; "
+            "fi; "
+            "exit \"$status\""
+        )
+        command = "bash -lc " + shlex.quote(script)
+        return [
+            TerminalCommand(
+                command=command,
+                max_timeout_sec=float("inf"),
+                block=True,
+            )
+        ]