Align javascript-sdk docs with the java-sdk/python-sdk documentation-parity standard - #147
Merged
Conversation
Codecov Report❌ Patch coverage is
Flags with carried forward coverage won't be shown. Click here to find out more.
... and 2 files with indirect coverage changes 🚀 New features to boost your workflow:
|
kowser-orkes
changed the title
v1r3n
approved these changes
Jul 29, 2026
Nothing in e2e/ ever invoked the downloaded `agentspan` binary (verified via grep across test_suite3_cli_tools/test_suite15_skills), and the one env var that would have wired it up (AGENTSPAN_CLI_PATH) was already removed in b336962 with no replacement. AGENTSPAN_CLI_VERSION only fed this now-dead step.
Reword remaining plain-prose "Agentspan"/"AgentSpan" product-name
mentions to Conductor terminology in AGENTS.md, cli-bin/shared.ts, and
docs/agents/{README,getting-started,framework-agents}.md.
Left untouched (real, not branding drift): the external `agentspan` CLI
binary name, AGENTSPAN_* env var identifiers (Stage 2), internal
`_agentspan` serializer markers, and the exported `AgentspanError` class.
…veness config AgentConfig's 7 worker/streaming/liveness knobs only read AGENTSPAN_* env vars, unlike resolveOrkesConfig.ts's CONDUCTOR_* -> AGENTSPAN_* fallback for connection settings. Give them the same alias treatment, closing the gap AGENTS.md itself flagged as "a possible follow-up." Additive and backward compatible -- existing AGENTSPAN_*-only setups are unaffected.
documentation-parity.md is an honest 3-way map (unlike Java/Python's 2-way one) -- it records JS's current structural gap against the Java/Python core/operations/agent-doc-tree split as tracked debt instead of implying parity that doesn't exist yet. Also lists JS-only-by-design pages and the shared (not JS-specific) LEASE_EXTENSION.md loose end. docs/README.md is a minimal hub (JS has no core-guide split to index yet) linking to the agent docs, API reference, and the parity map, so neither new page is orphaned. Wired into the root README's existing Documentation table, mirroring java-sdk/python-sdk's own hub link.
New `docs` job in pull_request.yml, mirroring java-sdk's ci.yml: - lycheeverse/lychee-action against README.md + docs/ (--include-fragments to also validate #anchor links) - a grep guard rejecting new "Agentspan"/"AgentSpan" prose Unlike java-sdk's tree-wide branding guard, this one is scoped to README.md/AGENTS.md/docs//cli-bin -- the areas the branding sweep actually covers. examples/, e2e/, and src/ still carry the intentionally-kept AGENTSPAN_* env var family and are out of scope here. The "retired documentation references" guard is deferred: nothing is retired yet (the flat docs/agents/*.md pages are still live). Running lychee locally surfaced a real, pre-existing bug: README.md's Documentation table linked to 5 docs/api-reference/*.md pages that were never written (AuthorizationClient, IntegrationClient, PromptClient, SchemaClient, SecretClient all exist in source with no reference page). Removed the 5 dead links and recorded the missing pages as a tracked, separately-scoped gap in documentation-parity.md.
Commit 8694426 ("Replace AGENTSPAN_SERVER_URL with CONDUCTOR_SERVER_URL") was a blind find-replace across 174 files. It correctly updated the files meant to migrate to CONDUCTOR_SERVER_URL, but also clobbered the one spot meant to keep an AGENTSPAN_SERVER_URL *fallback tier* -- resolveOrkesConfig.ts ended up checking CONDUCTOR_SERVER_URL twice instead of falling back to the legacy name, contradicting its own R3 comment and the identical pattern already used for auth key/secret two lines below it. Found via Stage 5's full unit-test run: 3 tests failed because their env var assignments and expected precedence no longer matched what the (also corrupted) test files asserted. Restored AGENTSPAN_SERVER_URL as the third fallback tier in resolveOrkesConfig.ts, and fixed the two test files' corrupted env var names/assignments to match.
Summarizes the parity map, docs hub, branding sweep, and new CI guards (Stages 1-4) and the resolveOrkesConfig fallback-tier fix Stage 5's validation surfaced. Ties back to java-sdk PR #144 / python-sdk PR #441.
…GENTSPAN_* fallback Matches java-sdk/python-sdk exactly (CONDUCTOR_AGENT_WORKER_POLL_INTERVAL etc., no legacy fallback) -- neither reference SDK carries an AGENTSPAN_* alias for these settings. Supersedes this branch's own prior CONDUCTOR_WORKER_* (no _AGENT_ segment) + AGENTSPAN_* fallback, added earlier in this same branch and never released.
Matches java-sdk's AgentException / python-sdk's ConductorAgentError -- neither reference SDK's base agent-error class carries the legacy product name. Breaking API rename (pre-1.0, no released version to deprecate through).
- advanced.md / api-reference.md / writing-agents.md: single CONDUCTOR_AGENT_* name per knob (no more dual reference), matching java-sdk's runtime.md style - getting-started.md: quickstart table now names the actual primary env vars (CONDUCTOR_AUTH_KEY/SECRET, not the AGENTSPAN_* fallback); dropped AGENTSPAN_API_KEY, a bearer-token option carried over from the original Agentspan TS SDK that nothing in this package reads - AGENTS.md: split the connection-config vs. worker/streaming/liveness-knob sentence (only the former keeps an AGENTSPAN_* fallback; the latter is CONDUCTOR_AGENT_*-only per the prior two commits) without naming the legacy identifiers - CI branding guard: dropped the now-unused AGENTSPAN_[A-Z_*]+/AgentspanError allowlist entries -- nothing in its scanned scope needs them any more - CHANGELOG.md: corrected the Stage 2 entry (still Unreleased) to describe the final CONDUCTOR_AGENT_* naming instead of the superseded alias framing Left untouched (separate, larger scope): AGENTSPAN_LLM_MODEL (~60 example files + e2e/helpers.ts convention), _agentspan serializer markers (framework-agents.md, source-coupled), resolveOrkesConfig.ts/logger.ts's AGENTSPAN_* connection/log-level fallback (bigger blast radius, real back-compat decision from the original merge).
…tirely resolveOrkesConfig.ts (server URL, auth key/secret) and DefaultLogger's log level no longer read AGENTSPAN_SERVER_URL/AGENTSPAN_AUTH_KEY/ AGENTSPAN_AUTH_SECRET/AGENTSPAN_LOG_LEVEL at all -- confirmed python-sdk's base Configuration class has zero AGENTSPAN_* concept for these settings either (grepped its actual config-resolution code, not just docs). Only CONDUCTOR_* is read now, matching java-sdk/python-sdk exactly. Breaking change for anyone migrating from the standalone @conductor-oss/conductor-agent-sdk package who kept AGENTSPAN_* env vars set -- rename to the CONDUCTOR_* equivalents. Updated tests to assert the legacy vars are now inert rather than testing fallback precedence; updated doc comments, examples/agents/README.md, and CHANGELOG.md to match.
…ding - AGENTSPAN_SECONDARY_LLM_MODEL -> CONDUCTOR_AGENT_SECONDARY_LLM_MODEL (examples/agents/settings.ts, 58-scatter-gather.ts) -- same sibling convention as AGENTSPAN_LLM_MODEL, renamed separately - AGENTSPAN_JUDGE_MODEL -> CONDUCTOR_AGENT_JUDGE_MODEL (e2e judge harness) - drop dead AGENTSPAN_* entries from runtime.test.ts's env save/restore lists -- inert now that the fallback is fully removed
…irely - CHANGELOG.md, AGENTS.md, config.ts, resolveOrkesConfig.ts, CI guard: reworded away from literal AGENTSPAN_* names, "matches java-sdk/ python-sdk exactly" framing, and the word "legacy" -- plain statements of current behavior only - deleted the 4 "ignores legacy AGENTSPAN_*" regression tests (config, createConductorClient, resolveOrkesConfig x2) and their now-dead env save/restore entries -- genericizing the env var name would have made them assert nothing meaningful, so removed rather than hollowed out - CHANGELOG's breaking-change entries lose the exact old env var names as a result; accepted per explicit direction, migrators fall back to this diff/PR description for the rename table
examples/agents/ had no package.json, so tsx/esbuild fell back to the repo root's (CJS, no "type" field) and rejected genuine top-level await with "Top-level await is currently not supported with the cjs output format" -- affected every example that doesn't wrap its body in main() (02-tools, 06-hitl, 09-human-in-the-loop, 09d-human-tool, 12-long-running, 18-manual-selection, 32-human-guardrail, 57-plan-dry-run, 63-deploy, 63b/63c/63d/63e). Added examples/agents/package.json with "type": "module", matching the pattern already used by the adk/langgraph/openai/vercel-ai example subdirs. Verified all 13 now run to completion against a live server; 01-basic-agent.ts (main()-wrapped style) still runs unaffected.
Split the flat advanced.md/api-reference.md/framework-agents.md/writing-agents.md
into docs/agents/{concepts,reference,frameworks}/ matching python-sdk's layout,
keeping JS's richer code-heavy content rather than shrinking to Python's terser
prose. Old flat pages kept as redirect stubs (Python's own pattern for superseded
pages) so existing links don't break.
A topic-by-topic content check against python-sdk's 23 concept/reference files
(not just file-existence) found and closed 4 real doc-only gaps: memory usage
guidance, a hand-authored agent-schema.json wire-contract reference (verified
against a live AgentConfigSerializer round-trip), naming the crash-recovery
pattern, and documenting the automatic SSE-fallback behavior.
Also corrected documentation-parity.md, which wrongly claimed JS lacks Google
ADK and OpenAI Agents SDK framework bridges -- both are supported via the same
detectFramework() duck-typing Python uses its own detection for.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Stage 9: add 19 short landing pages (server-setup, workers, workflows, reliability, security, etc.) linking into existing README/api-reference/ METRICS/LEASE_EXTENSION content, matching python-sdk's own thin-landing-page pattern over its deeper legacy docs. Rewrite docs/README.md to python-sdk's Start-here/Build/Operate/Reference shape. Stage 10: reconcile every file in python-sdk's docs/ tree, not just the directories already compared. Add docs/workflow-message-queue.md (previously undocumented outside a passing mention in the agent tools guide) after confirming JS's pullWorkflowMessages/waitForMessageTool cover the receive side but no client operation exists to push a message in (the generated OpenAPI client has no such endpoint; java-sdk has the same receive-only shape). Add the missing Pull Workflow Messages section to the pre-existing task-generators.md, and fix a stale JSDoc in tool.ts referencing a non-existent AgentRuntime.sendMessage method. Document Python's legacy deep-reference docs and internal design docs file-by-file in documentation-parity.md so nothing is unaccounted for. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
kowser-orkes
force-pushed
the
fix/align-documentation
branch
from
July 29, 2026 04:42
a503867 to
234516f
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Pull Request Title: Align javascript-sdk docs with the java-sdk/python-sdk documentation-parity standard
Pull Request type
Changes in this PR
agentspanCLI binary download inagent-e2e.yml(nothing invoked it)AGENTS.md,cli-bin/shared.ts,docs/agents/*.mdCONDUCTOR_*env var aliases forAgentConfig's 7 worker/streaming/liveness knobs, falling back to the existingAGENTSPAN_*namesdocs/documentation-parity.md— 3-way JS/Java/Python gap mapdocs/README.md— minimal documentation hubdocsjob:lycheelink check + a legacy-branding grep guard (scoped toREADME.md/AGENTS.md/docs//cli-bin/)README.mdpointing at reference pages that were never writtenresolveOrkesConfig.ts'sAGENTSPAN_SERVER_URLfallback tier, clobbered by an earlier find-replace (was checkingCONDUCTOR_SERVER_URLtwice instead of falling back to the legacy var); corrected the same corruption in two test filesOut of scope (tracked in
docs/documentation-parity.md):concepts//reference//frameworks/doc-tree restructuringsrc/agents/*.tscomments,examples/,e2e/Issue #
Alternatives considered
Full structural restructuring in this same PR — rejected, it's a content-authoring effort on the order of python-sdk PR #441, sized for its own PR.