fix(toolset): honour STACKONE_BASE_URL and remove documented fiction

Closed
WI
2mo ago
+32-57

Summary

Two Phase 1 patch fixes from the SDK platform rewrite proposal. Rebased onto 2.10.1.

STACKONE_BASE_URL is now honoured. It was ignored entirely, so a consumer pointing at staging silently talked to production (consumer contract §2.4, defect 7). Precedence is explicit arg > env var > default, matching the STACKONE_API_KEY handling on the line above and node's behaviour. The docstring documents it rather than leaving a constructor that reads an undocumented env var.

Three documented-but-untrue claims removed (consumer contract §3), each verified against the source first:

ClaimReality
configure_implicit_feedback + the "Implicit Feedback (Beta)" sectionDoes not exist. models.py carries a # Implicit feedback removed marker where it used to live.
Action-filter exclusions like "!*_delete_*"_filter_by_action is a bare any(fnmatch(...)) — no negation. fnmatch("sf_delete_lead", "!*_delete_*") is False, so it matches nothing and excludes nothing.
"This tool is automatically included in the toolset"Never injected client-side. get_tool("tool_feedback") returned None, so the next line of the shipped example raised AttributeError.

The feedback docs now point at the MCP-served stackone_submit_feedback and the create_feedback_tool path that actually works — verified by executing it.

Scope changes after review

Three things were dropped from earlier revisions of this branch:

  • mcp<2.0.0 pin — already on main via #194. My version was byte-identical. Removed.
  • Widening pydantic-ai-slim to <3.0.0 — removed. See below.
  • Client-side feedback-tool auto-injection — removed. The MCP service already registers stackone_submit_feedback as a global, always-present tool (mcp.service.ts:448, unscoped to account or tool mode), so injecting a second tool_feedback gave one capability two names, two schemas and two routes, and it bypassed the provider/action filters. Node's auto-append is the same defect rather than the target state; both hand-built tools go together in the MCP-execution rewrite.

On the pydantic-ai cap

I initially widened pydantic-ai-slim to <3.0.0, having measured that the adapter works fine on 2.x: Tool.from_schema is signature-identical on 1.83.0 and 2.42.0, and all 11 integration tests (including a live Agent.run_sync) pass on both majors.

That is still true, but widening it here was wrong. #195 capped the pydantic-ai and examples extras together deliberately, and the resolver shows why they cannot move apart:

stackone-ai:dev depends on pydantic-ai-slim>=2.18.0
and stackone-ai[examples] depends on pydantic-ai>=1.83.0,<2.0.0
-> incompatible -> your project's requirements are unsatisfiable

So moving to pydantic-ai 2.x means widening both extras and verifying the example scripts (crewai / langgraph / openai) on 2.x — a coupled dependency migration, not a patch. It also reds uv lock --check, which CI runs. Worth doing as its own PR; the evidence above is the starting point.

One related gap worth recording: pydantic_ai is in no dependency group, so pytest.importorskip skips all 11 integration tests silently in CI. Whatever upper bound we settle on, nothing currently exercises it.

Verified

  • Suite: 277 passed / 21 skipped. The 9 failures are pre-existing — identical count on clean origin/main (langgraph and mcp optional deps absent locally).
  • uv lock --check: passes (this is what CI's uv sync --all-extras --locked enforces).
  • ruff check: clean.
  • Precedence: explicit https://x.example.com wins over env; env https://staging.example.com used when no arg; default otherwise.
  • Downstream consumers: stackone-adk-plugin 32/32 green against this branch. pydantic-ai-harness[stackone] does not depend on stackone-ai at all (it uses fastmcp + pydantic-ai-slim directly), so it is unaffected.

Noted, not fixed

Out of scope for this change, but found while verifying it:

  • StackOneTool.call() accepts an options kwarg and drops it — neither models.py:396 nor :398 forwards it to execute().
  • create_feedback_tool is absent from __all__; it is only reachable as stackone_ai.feedback.tool.create_feedback_tool.
  • __init__.py hardcodes __version__ while toolset.py:84 derives it from importlib.metadata — the same drift class as the hardcoded stackone-python/1.0.0 User-Agent in contract §7.
  • .hypothesis/ is not in .gitignore.

🤖 Generated with Claude Code