fix(devkit): testkit host-stubs cover SubagentConfig + Knobs so register() runs host-free (protoLabsAI#1773)

The plugin-devkit testkit's default host-stubs omitted `graph.subagents.config`
entirely (ModuleNotFoundError) and handed back a raise-when-called `Knobs` /
`make_knob_tools` from `graph.sdk`. So a scaffolded plugin whose `register()`
registers a subagent (`registry.register_subagent(SubagentConfig(...))`) or wires
runtime knobs failed its OWN host-free smoke test before the author wrote a line.

These seams are CONSTRUCTED at register() time, not merely imported, so they need
permissive RECORD-ONLY stand-ins (not the raise-when-called placeholder):

- Stub `graph.subagents` + `graph.subagents.config` exposing `SubagentConfig`, a
  record that stores its kwargs as attributes — `from graph.subagents.config import
  SubagentConfig` imports and `reg.subagents[0].name` is assertable.
- `graph.sdk` now exposes a chainable no-op `Knobs` (`.define`/`.preset` return self,
  reads mirror the surface) and `make_knob_tools(...)` returning record-only stub
  tools named like the real `<prefix>_knobs`/`_tune`/`_preset` — a plugin can
  `register_tools(make_knob_tools(...))` host-free and the contribution stays
  assertable. The remaining `graph.sdk` seams (complete/run_subagent/...) stay
  raise-unpatched so a model-touching test still fails loudly if unpatched.

`graph/plugins/testkit.py` is the single source of truth — the scaffolder vendors it
verbatim into each plugin's `tests/_plugin_testkit.py`, so newly-scaffolded plugins
inherit the fix automatically.

Closes protoLabsAI#1764

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: mabry1985

graph/plugins/testkit.py

@@ -109,18 +109,83 @@ def __getattr__(self, item: str):
         return _raise_unpatched(f"{self.__name__}.{item}")
 
 
+# Some host seams a plugin doesn't just IMPORT but CALLS at register() time — it constructs a
+# ``SubagentConfig`` and builds knob tools while wiring the registry. Those can't be the
+# raise-when-called placeholder (that turns a scaffolded plugin's own smoke test red before it
+# writes a line — #1764); they need permissive, RECORD-ONLY stand-ins that run host-free while
+# keeping the contribution assertable.
+
+
+class _StubSubagentConfig:
+    """Stand-in for ``graph.subagents.config.SubagentConfig`` — stores every kwarg as an
+    attribute, so ``registry.register_subagent(SubagentConfig(name=..., ...))`` runs with no
+    host and the captured config stays assertable (``reg.subagents[0].name``)."""
+
+    def __init__(self, **kwargs):
+        self.__dict__.update(kwargs)
+
+
+class _StubKnobs:
+    """Chainable no-op stand-in for ``graph.knobs.Knobs`` (re-exported from ``graph.sdk``):
+    ``define``/``preset`` record the declaration and return ``self`` so a plugin's fluent knob
+    setup runs host-free; the reads mirror the real surface so an engine that reads a default
+    back at register() time still works (and the record stays assertable)."""
+
+    def __init__(self, *_a, **_k):
+        self.defined: dict = {}
+        self.defined_presets: dict = {}
+
+    def define(self, name=None, default=None, **_k) -> "_StubKnobs":
+        if name is not None:
+            self.defined[name] = default
+        return self
+
+    def preset(self, name=None, overrides=None, **_k) -> "_StubKnobs":
+        if name is not None:
+            self.defined_presets[name] = dict(overrides or {})
+        return self
+
+    def get(self, name):
+        return self.defined.get(name)
+
+    def values(self) -> dict:
+        return dict(self.defined)
+
+    def presets(self) -> dict:
+        return dict(self.defined_presets)
+
+
+def _make_knob_tools(
+    knobs=None, *, prefix: str = "knobs", show: bool = True, tune: bool = True, presets: bool = True, **_k
+) -> list:
+    """Stand-in for ``graph.knobs.make_knob_tools`` — returns one harmless, record-only stub
+    tool per enabled control, named like the real ``<prefix>_knobs`` / ``_tune`` / ``_preset``,
+    so a plugin can ``registry.register_tools(make_knob_tools(...))`` with no host and the tool
+    contribution stays assertable (instead of the old raise-when-called placeholder)."""
+    made: list = []
+    for enabled, suffix in ((show, "knobs"), (tune, "tune"), (presets, "preset")):
+        if enabled:
+            made.append(types.SimpleNamespace(name=f"{prefix}_{suffix}"))
+    return made
+
+
 # Default host surface, derived from what real plugins import (spacetraders, project_board,
 # notes, …). `extra` lets a plugin add its own; anything already importable is left alone.
 def _default_stubs() -> dict:
     return {
         "graph": {},
-        "graph.sdk": {},  # run_subagent / subagent_types / config / complete
+        # Knobs/make_knob_tools are CALLED at register() time, so they're real stand-ins (not
+        # raise-when-called); the rest (run_subagent / subagent_types / config / complete) stay
+        # raise-unpatched placeholders — patch them in a test that exercises the model seam.
+        "graph.sdk": {"Knobs": _StubKnobs, "make_knob_tools": _make_knob_tools},
         "graph.config": {"LangGraphConfig": type("LangGraphConfig", (), {})},
         "graph.config_io": {"secrets_yaml_path": lambda: Path("config/secrets.yaml")},
         "graph.goals": {},
         "graph.goals.types": {
             "VerifyResult": type("VerifyResult", (), {"__init__": lambda self, **kw: self.__dict__.update(kw)})
         },
+        "graph.subagents": {},
+        "graph.subagents.config": {"SubagentConfig": _StubSubagentConfig},
         "knowledge": {},
         "knowledge.store": {"KnowledgeStore": type("KnowledgeStore", (), {})},
     }

tests/test_plugin_testkit.py

@@ -208,3 +208,67 @@ def test_install_host_stubs_is_idempotent():
     first = testkit.install_host_stubs(extra={"phantom_host": {}, "phantom_host.sdk": {}})
     second = testkit.install_host_stubs(extra={"phantom_host": {}, "phantom_host.sdk": {}})
     assert "phantom_host.sdk" in first and second == []  # nothing re-installed the 2nd time
+
+
+# ── subagent-config + knobs stubs (#1764) ────────────────────────────────────────────
+# A plugin's register() doesn't just IMPORT host seams — it CONSTRUCTS a SubagentConfig and
+# builds knob tools inline. Before #1764 `graph.subagents.config` was unstubbed
+# (ModuleNotFoundError) and `graph.sdk` handed back a raise-when-called Knobs, so a scaffolded
+# plugin that registered a subagent or used Knobs failed its OWN host-free smoke test.
+
+
+def test_default_stubs_expose_a_permissive_subagent_config():
+    # #1764: graph.subagents.config.SubagentConfig must be a record-only stand-in that stores
+    # its kwargs, so register_subagent(SubagentConfig(...)) runs host-free and stays assertable.
+    specs = testkit._default_stubs()
+    assert "graph.subagents.config" in specs and "graph.subagents" in specs  # parent pkg too
+    SubagentConfig = specs["graph.subagents.config"]["SubagentConfig"]
+    sc = SubagentConfig(name="architect", description="d", system_prompt="p", tools=["read_file"])
+    assert sc.name == "architect"
+    assert sc.tools == ["read_file"]
+
+
+def test_default_stubs_expose_chainable_knobs_and_a_tool_list():
+    # #1764: graph.sdk Knobs/make_knob_tools are called at register() time, so they must be
+    # real stand-ins (chainable no-op + list), not the raise-when-called placeholder.
+    specs = testkit._default_stubs()
+    Knobs = specs["graph.sdk"]["Knobs"]
+    make_knob_tools = specs["graph.sdk"]["make_knob_tools"]
+    knobs = Knobs()
+    assert knobs.define("depth", 3, lo=1, hi=5).preset("deep", {"depth": 5}) is knobs  # chainable
+    assert knobs.get("depth") == 3  # recorded default reads back
+    tools = make_knob_tools(knobs, prefix="demo")
+    assert isinstance(tools, list) and [t.name for t in tools] == ["demo_knobs", "demo_tune", "demo_preset"]
+
+
+def test_register_with_subagent_and_knobs_runs_against_the_stubs(monkeypatch):
+    # The end-to-end shape #1764 fixes: a register() that registers a subagent (SubagentConfig)
+    # AND wires knob tools (Knobs/make_knob_tools). In-repo the real graph host is importable, so
+    # mask just the two leaf modules the register() imports with the STUBS — exercising exactly
+    # the standalone code path a scaffolded plugin runs. monkeypatch restores sys.modules after.
+    specs = testkit._default_stubs()
+    for name in ("graph.sdk", "graph.subagents.config"):
+        monkeypatch.setitem(sys.modules, name, testkit._StubModule(name, specs[name]))
+
+    def register(registry):
+        from graph.sdk import Knobs, make_knob_tools
+        from graph.subagents.config import SubagentConfig
+
+        knobs = Knobs().define("depth", 3, lo=1, hi=5).preset("deep", {"depth": 5})
+        registry.register_tools(make_knob_tools(knobs, prefix="demo"))
+        registry.register_subagent(
+            SubagentConfig(
+                name="architect",
+                description="Designs the plugin.",
+                system_prompt="You are the architect.",
+                tools=["read_file"],
+            )
+        )
+
+    reg = testkit.FakeRegistry()
+    register(reg)  # must not raise — the whole point of #1764
+
+    assert len(reg.subagents) == 1  # the subagent contribution is recorded + assertable
+    assert reg.subagents[0].name == "architect"
+    assert reg.subagents[0].tools == ["read_file"]
+    assert [t.name for t in reg.tools] == ["demo_knobs", "demo_tune", "demo_preset"]  # knob tools wired