superqode 0.2.4__tar.gz → 0.2.5__tar.gz

{superqode-0.2.4 → superqode-0.2.5}/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.5] - 2026-07-04
+
+### Added
+
+- **Harbor / Terminal-Bench compatibility for the ACP agent** - The ACP server now honors Harbor's `HARBOR_ACP_REQUESTED_MODEL` environment variable when resolving the session model and implements ACP `session/set_model`, so `harbor run --agent acp` can drive SuperQode on Terminal-Bench using the benchmark's `--model` flag with no wrapper code.
+- **Harness template selection over ACP** - `SUPERQODE_ACP_SPEC` (and `serve acp --spec`) now accepts `template:<name>` to pin any built-in harness template for a session without a spec file, enabling harness-variant comparisons in benchmark containers.
+- **`benchmark-coding` template** - An autonomous variant of the coding harness for unattended benchmark runs: yolo approvals, and a system stance that never asks the user questions, investigates recoverable state exhaustively (reflog, stashes, backups), always applies a concrete attempt, and verifies before finishing.
+- **ACP Agent Server documentation** - Added the ACP Agent Server guide covering editor setup, harness and model resolution, template selection, and running SuperQode on Terminal-Bench with Harbor, plus `serve acp` CLI reference coverage.
+
+### Changed
+
+- **Release metadata** - Bumped the package version and runtime `__version__` to `0.2.5`.
+
 ## [0.2.4] - 2026-07-04
 
 ### Added

{superqode-0.2.4/src/superqode.egg-info → superqode-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: superqode
-Version: 0.2.4
+Version: 0.2.5
 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.4 → superqode-0.2.5}/pyproject.toml

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

{superqode-0.2.4 → superqode-0.2.5}/src/superqode/__init__.py

@@ -30,4 +30,4 @@ __all__ = [
     "sidebar",
 ]
 
-__version__ = "0.2.4"
+__version__ = "0.2.5"

{superqode-0.2.4 → superqode-0.2.5}/src/superqode/acp/server.py

@@ -31,6 +31,7 @@ from acp import (
     InitializeResponse,
     NewSessionResponse,
     PromptResponse,
+    SetSessionModelResponse,
     run_agent,
     start_tool_call,
     text_block,
@@ -168,7 +169,8 @@ def discover_session_spec(cwd: Path, harness_dir: Path | None = None) -> Path |
 
 
 def resolve_provider_model(spec: Any, provider: str = "", model: str = "") -> tuple[str, str]:
-    """Resolve provider/model: explicit args → ACP env vars → model_policy.primary."""
+    """Resolve provider/model: explicit args → ACP env vars → Harbor requested model
+    → model_policy.primary."""
     from superqode.providers.model_specs import (
         normalize_model_for_provider,
         normalize_provider_id,
@@ -185,6 +187,17 @@ def resolve_provider_model(spec: Any, provider: str = "", model: str = "") -> tu
         if parsed_model.provider:
             provider, model = parsed_model.provider, parsed_model.model
 
+    # Harbor's ACP runner exports the benchmark's --model for the agent process;
+    # honoring it makes SuperQode work on Terminal-Bench without a wrapper.
+    harbor_requested = os.environ.get("HARBOR_ACP_REQUESTED_MODEL", "").strip()
+    if (not provider or not model) and harbor_requested:
+        parsed_requested = split_provider_model_ref(harbor_requested)
+        if parsed_requested.provider:
+            provider = provider or parsed_requested.provider
+            model = model or parsed_requested.model
+        else:
+            model = model or harbor_requested
+
     primary = getattr(getattr(spec, "model_policy", None), "primary", None)
     if (not provider or not model) and primary:
         parsed_primary = split_provider_model_ref(str(primary))
@@ -311,6 +324,23 @@ class SuperQodeAcpAgent:
         self._sessions.pop(session_id, None)
         return None
 
+    async def set_session_model(
+        self, model_id: str, session_id: str, **kwargs: Any
+    ) -> SetSessionModelResponse:
+        """Switch the session's model; accepts `provider/model` or bare model ids."""
+        from superqode.providers.model_specs import split_provider_model_ref
+
+        state = self._sessions.get(session_id)
+        if state is None:
+            raise RequestError.invalid_params({"reason": f"Unknown session: {session_id}"})
+        parsed = split_provider_model_ref(str(model_id))
+        if parsed.provider:
+            state.provider = parsed.provider
+            state.model = parsed.model
+        else:
+            state.model = str(model_id)
+        return SetSessionModelResponse()
+
     async def cancel(self, session_id: str, **kwargs: Any) -> None:
         state = self._sessions.get(session_id)
         if state is not None:
@@ -477,10 +507,14 @@ class SuperQodeAcpAgent:
 
     def _load_spec(self, cwd: Path) -> Any:
         from superqode.harness import load_harness_spec
-        from superqode.harness.templates import coding_template
+        from superqode.harness.templates import coding_template, get_harness_template
 
-        explicit = self._spec_path or os.environ.get("SUPERQODE_ACP_SPEC", "").strip()
+        explicit = str(self._spec_path or os.environ.get("SUPERQODE_ACP_SPEC", "")).strip()
         if explicit:
+            # `template:<name>` selects a built-in template — no spec file needed,
+            # which is how benchmark containers pin a harness variant per run.
+            if explicit.startswith("template:"):
+                return get_harness_template(explicit.removeprefix("template:"))
             return load_harness_spec(Path(explicit).expanduser())
         found = discover_session_spec(cwd, self._harness_dir)
         if found is not None:

{superqode-0.2.4 → superqode-0.2.5}/src/superqode/harness/templates.py

@@ -223,8 +223,49 @@ def minimax_coding_template() -> HarnessSpec:
     )
 
 
+_BENCHMARK_STANCE = """You are running unattended in a headless benchmark environment.
+
+- There is NO user available. Never ask questions, never request confirmation, and
+  never end your turn waiting for input. A response that asks a question scores zero.
+- Investigate exhaustively with your tools before concluding anything is missing or
+  impossible: inspect history, logs, hidden files, and recoverable state (for example
+  `git reflog`, `git fsck --lost-found`, `git stash list`, backup and temp files).
+- Always attempt a concrete solution and apply it with your tools. A reasonable
+  attempt scores better than a perfect explanation with no changes.
+- Before finishing, verify your work by running the relevant commands or tests and
+  fix what fails. Finish with a short summary of what you changed."""
+
+
+def benchmark_coding_template() -> HarnessSpec:
+    """Coding harness tuned for unattended benchmark runs (Harbor, Terminal-Bench)."""
+    base = coding_template(name="benchmark-coding")
+    agents = tuple(
+        AgentSpec(**{**agent.__dict__, "system_prompt": _BENCHMARK_STANCE}) for agent in base.agents
+    )
+    return HarnessSpec(
+        **{
+            **base.__dict__,
+            "description": (
+                "Autonomous coding harness for headless benchmark runs: never asks the "
+                "user, investigates exhaustively, always attempts and verifies a fix."
+            ),
+            "agents": agents,
+            "execution_policy": ExecutionPolicySpec(
+                sandbox="local",
+                approval_profile="yolo",
+                allow_read=True,
+                allow_write=True,
+                allow_shell=True,
+            ),
+            "metadata": {"template": "benchmark-coding"},
+        }
+    )
+
+
 BUILTIN_TEMPLATES = {
     "coding": coding_template,
+    "benchmark-coding": benchmark_coding_template,
+    "benchmark_coding": benchmark_coding_template,
     "no-tool": no_tool_template,
     "no_tool": no_tool_template,
     "gemma4-coding": gemma4_coding_template,

{superqode-0.2.4 → superqode-0.2.5/src/superqode.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: superqode
-Version: 0.2.4
+Version: 0.2.5
 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.4 → superqode-0.2.5}/tests/test_acp_server.py

@@ -165,6 +165,89 @@ def test_resolve_provider_model_explicit_wins():
     assert model == "gpt-4o-mini"
 
 
+def test_resolve_provider_model_honors_harbor_requested_model(monkeypatch):
+    monkeypatch.setenv("HARBOR_ACP_REQUESTED_MODEL", "ollama/gemma4:e4b")
+    spec = SimpleNamespace(model_policy=SimpleNamespace(primary=None))
+    provider, model = resolve_provider_model(spec)
+    assert provider == "ollama"
+    assert model == "gemma4:e4b"
+
+
+def test_resolve_provider_model_harbor_beats_spec_primary(monkeypatch):
+    # The benchmark's --model is the run contract: it must win over a spec default.
+    monkeypatch.setenv("HARBOR_ACP_REQUESTED_MODEL", "openai/gpt-5")
+    spec = SimpleNamespace(model_policy=SimpleNamespace(primary="ollama/qwen3-coder"))
+    provider, model = resolve_provider_model(spec)
+    assert provider == "openai"
+    assert model == "gpt-5"
+
+
+async def test_set_session_model_updates_state():
+    session = FakeSession()
+    agent, _ = make_agent_with_session(session)
+    response = await agent.set_session_model(model_id="openrouter/qwen3-coder", session_id="sess-1")
+    assert response is not None
+    state = agent._sessions["sess-1"]
+    assert state.provider == "openrouter"
+    assert state.model == "qwen3-coder"
+
+
+async def test_set_session_model_bare_model_keeps_provider():
+    session = FakeSession()
+    agent, _ = make_agent_with_session(session)
+    await agent.set_session_model(model_id="gemma4:e4b", session_id="sess-1")
+    state = agent._sessions["sess-1"]
+    assert state.provider == "ollama"
+    assert state.model == "gemma4:e4b"
+
+
+async def test_set_session_model_unknown_session_raises():
+    agent = SuperQodeAcpAgent()
+    with pytest.raises(Exception):
+        await agent.set_session_model(model_id="x/y", session_id="nope")
+
+
+def test_load_spec_template_name_from_env(monkeypatch, tmp_path):
+    monkeypatch.setenv("SUPERQODE_ACP_SPEC", "template:qwen-coding")
+    agent = SuperQodeAcpAgent()
+    spec = agent._load_spec(tmp_path)
+    assert "qwen" in spec.name.lower()
+
+
+def test_load_spec_unknown_template_raises(monkeypatch, tmp_path):
+    monkeypatch.setenv("SUPERQODE_ACP_SPEC", "template:not-a-real-template")
+    agent = SuperQodeAcpAgent()
+    with pytest.raises(Exception):
+        agent._load_spec(tmp_path)
+
+
+def test_benchmark_coding_template_is_autonomous():
+    from superqode.harness.templates import get_harness_template
+
+    spec = get_harness_template("benchmark-coding")
+    assert spec.execution_policy.approval_profile == "yolo"
+    assert spec.flavor.value == "coding"
+    stance = spec.agents[0].system_prompt or ""
+    assert "Never ask questions" in stance
+    assert "git reflog" in stance
+
+
+def test_benchmark_stance_reaches_agent_job_description():
+    # The stance only matters if it lands in the compiled profile the loop runs with.
+    from superqode.harness.compiler import compile_to_headless_profile
+    from superqode.harness.templates import get_harness_template
+
+    profile = compile_to_headless_profile(get_harness_template("benchmark-coding"))
+    assert "headless benchmark environment" in (profile.job_description or "")
+
+
+def test_load_spec_benchmark_template_via_env(monkeypatch, tmp_path):
+    monkeypatch.setenv("SUPERQODE_ACP_SPEC", "template:benchmark-coding")
+    agent = SuperQodeAcpAgent()
+    spec = agent._load_spec(tmp_path)
+    assert spec.name == "benchmark-coding"
+
+
 async def test_prompt_streams_events_as_session_updates():
     session = FakeSession(
         events=[