Keep AGENTSPAN_* env vars and AgentspanError working, and validate the agent schema

[ambiorix2099]

Two focused follow-ups to #147. Narrowed from #148 (now closed) to only what #147 didn't cover.

1. The rename is currently a silent break — a0235ea

#147 removed the AGENTSPAN_* names outright. Two of the three failure modes give the user nothing to go on:

What was set	Now	Symptom
AGENTSPAN_SERVER_URL	Not read at all. resolveOrkesConfig's agent-layer tier was removed entirely, not renamed	Silent. Falls through to http://localhost:8080 and fails against the wrong server
AGENTSPAN_AUTH_KEY / _SECRET	Not read	Silent. Unauthenticated requests
AGENTSPAN_WORKER_*, LIVENESS_*, STREAMING_*, AUTO_START_WORKERS, LLM_MODEL	Not read	Silent. Reverts to defaults
AGENTSPAN_LOG_LEVEL	Not read	Silent
import { AgentspanError }	Renamed, no alias	Loud — compile error

This restores all of them as deprecated fallbacks that warn once per name per process.

It does not re-litigate #147's design. Each legacy name maps to whatever the code reads now, rather than reintroducing the agent-layer connection tier #147 deliberately deleted — connection and auth stay on the core CONDUCTOR_* vars, agent behaviour knobs stay on CONDUCTOR_AGENT_*. The result is that #147's shape is preserved and the migration stops being breaking.

CONDUCTOR_* env → explicit config → deprecated AGENTSPAN_* → localhost:8080

AgentspanError returns as a direct alias — the same class object, not a subclass — so instanceof works in both directions and existing catch blocks keep working. Value and type are both exported, so const e: AgentspanError still compiles. Verified against the built dist/.

Two deliberate asymmetries, both commented in the code:

• AGENTSPAN_LOG_LEVEL falls back silently — warning there would log through the very logger whose level is still being resolved.
• e2e/helpers.ts carries its own fallback, because that suite ships as a release bundle for downstream repos and the SDK-level alias doesn't cover vars the harness reads directly.
• The helper is duplicated between src/agents and src/sdk rather than shared, because AGENTS.md forbids the agent layer importing from src/sdk outside agent-client.ts and worker.ts.

Adds 14 tests. #147 mechanically renamed the existing suite, so without these the compat guarantee has zero coverage.

2. agent-schema.json ships unvalidated — 284c94d

#147 added docs/agents/reference/agent-schema.json — the wire shape AgentConfigSerializer emits, shared with the Python and Java SDKs — with nothing checking it. It can drift from the serializer silently, leaving a documented contract that quietly stops describing reality.

Adds scripts/verify-agent-schema.mjs, wired as npm run verify:agent-schema and run in the existing docs job. Follows the verify-dist.mjs pattern already in this repo rather than transliterating python-sdk's pytest approach.

It selects the Ajv entrypoint from $schema (the file is 2020-12; Ajv's default export is draft-07), validates all 19 e2e/_configs/ fixtures, and asserts 8 invariants resolved through the root $ref so they survive restructuring.

Two of those invariants encode the existing design rather than second-guessing it: agentConfig stays closed and tool stays open. additionalProperties: false on agentConfig is what makes this a real gate — adding a serializer field now fails CI until the contract is updated.

Good news from writing it: all 19 fixtures pass, so the contract #147 documented does match current serializer output.

Adds ajv ^8.17.1 explicitly. It was already there transitively via eslint, but a CI gate resting on a transitive dep is how gates silently stop running.

Verification

Check	Result
Lint	0 errors, 360 warnings — identical to main
Unit tests	1580 / 80 suites (main: 1566 / 79)
tsc --noEmit	Zero net new errors vs main (455 pre-existing both sides)
Build + verify:dist	6 entrypoints, ESM + CJS
Alias behaviour	Verified against built dist/ — same class object, instanceof both ways
Env fallback	Smoke-tested: warns once, resolves the legacy value
Schema verifier	19 fixtures + 8 invariants; negative-tested two ways
Existing branding grep	Still passes

Note

AgentspanMetadata in the langchain and langgraph wrappers was left un-renamed by #147 while the error class was renamed. That's a naming inconsistency rather than a compat break, so I left it alone — flagging it rather than widening this PR.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

Flag	Coverage Δ
integration-v4-sm	41.52% <44.60%> (+0.05%)	⬆️
integration-v5-sdkdev	43.99% <44.60%> (+0.10%)	⬆️
unit	74.00% <100.00%> (+0.12%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
src/agents/config.ts	100.00% <100.00%> (ø)
src/agents/errors.ts	90.73% <100.00%> (+1.11%)	⬆️
src/agents/legacy-env.ts	100.00% <100.00%> (ø)
...reateConductorClient/helpers/resolveOrkesConfig.ts	100.00% <100.00%> (ø)
src/sdk/helpers/logger.ts	95.45% <100.00%> (+2.77%)	⬆️

... and 1 file with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[ambiorix2099]

Duplicate work