fix: restore span instrumentation after the base-SDK hook consolidation

[ash-krnl]

Why

setup_instrumentation called openbox_langgraph.otel_setup.setup_opentelemetry_for_governance, which in openbox-langgraph-sdk-python 1.0.0 is no longer an implementation — its whole body raises OpenBoxConfigError. The call sat inside a best-effort except, so every run logged

OTel instrumentation unavailable; spans disabled

and carried on. Policy arms still evaluated, which is why the demo passed 4/4 while recording span_count: 0 on every event — governed at the activity layer, blind below it. No behavior rule could ever match, because there were no spans to match on.

Nothing here was LangGraph-shaped: that SDK was a route to the openbox_core underneath it. >=0.2.0 with no upper bound admitted the 1.0.0 that removed the entry point, so the break arrived with no code change on this side.

What changed

Instrumentation — builds on openbox_core directly: OpenBoxConfig.resolve → private ContextStore → OpenBoxRuntime → InstrumentationManager(extra_ignored_urls={api_url}) → install(). One runtime per middleware (runtime.close() clears its store, so sharing one lets a teardown blast a concurrent turn). DID and private key threaded through so the runtime's client keeps signing instead of downgrading to bare-Bearer.

Attribution — register_activity binds an ActivityContext on the store; clear_activity resets the token. The WorkflowSpanBuffer per-workflow registration is gone: every span resolves a context already carrying workflow_id, run_id and workflow_type.

span_aliases.py (new) — spans arrived with only url.full / http.request.method, and the status code reached attributes under neither convention. Core stores the attributes JSONB and has no columns for the flat HTTP fields, while every reader wants the legacy keys: the dashboard's tree builds its link from attrs["http.url"] and its badge from attrs["http.response.status_code"], and core's own spanToSpanData reads attrs["http.url"] for fingerprint identity. So spans rendered with no link and no status. This mirrors the flat fields into attributes under the legacy keys — additive, never overwriting. Extended to the db and file families for the same reason.

db_drivers.py (new) — no SQL produced a span at all. install_dbapi patches the governance seam (CursorTracer.traced_execution) but instruments no driver, and a CursorTracer only exists if a driver instrumentor built one. install_redis and install_asyncpg patch theirs; the DB-API family had no equivalent step anywhere. The legacy setup_database_instrumentation did that half.

No more false success — a base SDK installed without its [http] extra arms the runtime, declines every installer and records zero spans. setup_instrumentation now says so loudly.

Dependency — openbox-sdk-python[http]>=1.2.0,<2, replacing the LangGraph SDK and the langgraph/langchain-core/langsmith it dragged in. [http] is not optional: the opentelemetry-instrumentation-* packages live behind it.

file_spans.py — reports honestly rather than installing nothing. Core's _file_span_name derives the name from the open mode, so writes-filed-as-reads is fixed upstream; per-operation timing is not, so file start/completion pairs still share a timestamp.

Verification

Environment	Result
local	4/4 scenarios, spans with url/method/status
staging	4/4 plumbing (agent has no controls attached, so all arms allow)
production	4/4, Send_Invoice → require_approval, signing accepted by a signing_required agent

• 87 tests pass
• A clean venv installs no LangGraph, and import openbox_langgraph raises ModuleNotFoundError while the demo still runs 4/4
• started → completed pairs intact, verified against pre-port sessions in the same database
• A 24-span matrix run covers every producible type: 5 HTTP verbs incl. a 404, llm_completion, database_{select,insert,update,delete,query}, file_{read,write}

Known limits, unchanged by this PR

• llm_routing / llm_provenance need openbox.routing.stage=preflight or gen_ai.generation.id; this SDK emits neither, so the routing panel stays empty for Citadel agents
• llm_embedding / llm_tool_call / mcp_tool_call classify off the span name or an mcp.method attribute
• file_delete is impossible: file hooks patch only builtins.open/io.open, so os.remove is invisible
• db_operation is sent but core classifies from the span name — fixed separately in openbox-sdk-python

🤖 Generated with Claude Code