Align JavaScript SDK documentation with the Java SDK's structure and Conductor-agent terminology by ambiorix2099 · Pull Request #148 · conductor-oss/javascript-sdk

ambiorix2099 · 2026-07-29T01:50:52Z

Ports the work from conductor-oss/python-sdk#441 to this SDK. Three commits, reviewable in order: rebrand → docs → CI.

The premise was verified first, and it holds here

When this was attempted against the Java SDK the premise turned out inverted, because Java was the source of the structure, not the target. That is not the case here. The decisive evidence is what PR 441 modified under docs/:

docs/agents/README.md   advanced.md   api-reference.md
framework-agents.md     getting-started.md   writing-agents.md

That is byte-for-byte the six-file layout this repo has today. This repo sits at Python's pre-PR position. Zero of the PR's 43 added doc files existed here, and CONDUCTOR_AGENT_ appeared zero times.

Two corrections to the upstream framing, both confirmed against the merged diff and python-sdk@main:

The driver was a rebrand, not a server URL change. Agentspan → Conductor. 294 files here contained agentspan; 189 contained AGENTSPAN_, across 18 distinct names.
The PR description's backward-compatibility claim is false, and so is the usual correction to it. It claims env-var and error aliases were kept. In fact runtime/config.py deletes every AGENTSPAN_* read ("Only CONDUCTOR_AGENT_* settings are supported."), and AgentspanError was renamed outright — python-sdk@main contains zero occurrences. The added test_agent_error_alias.py only asserts two import paths resolve to the same class. Neither kind of alias survived.

This PR keeps both, deliberately, because this repo already ships a spec'd compat posture Python discarded (resolveOrkesConfig.ts, spec R3) and AgentspanError is the exported base of 12 subclasses.

1. Rebrand (`2a613f8`)

Nothing breaks at runtime. Old env names resolve as deprecated fallbacks warning once per name per process; the error alias is the same class object, not a subclass, so instanceof works both directions, and both the value and type are exported. AGENTSPAN_LOG_LEVEL falls back silently — warning there means logging through the logger whose level is still being resolved. e2e/helpers.ts carries its own fallback because that suite ships as a release bundle and the SDK-level alias doesn't cover vars the harness reads directly.

The only observable change is error.name on a base-class instance.

Names deliberately left alone — the external-name set turned out to be roughly twice what an initial survey suggests, and includes traps worse than agentspan.embedded:

Category	Examples
Cross-SDK wire keys	`__agentspan_ctx__`, `_agentspan.llm`, `_agentspan_human_task`, `__agentspan_sdk__.cjs`
Server boot properties	`agentspan.embedded`, `agentspan.default-context-window`
External repos / npm scope	`agentspan-ai/agentspan`, `@agentspan-ai`, `agentspan-ai/codingexamples`
External CLI	the `agentspan` binary, `~/.agentspan/config.json`, `agentspan deploy` (198 occurrences)
Version-qualified product refs	`agentspan <= 0.4.2`, `agentspan server > 0.4.2` — renaming these makes them factually false

Useful invariant: every cross-SDK wire key is underscore-prefixed. That's the fastest way to tell a wire contract from prose. Full table now in AGENTS.md.

A blanket sweep would have broken an npm scope under node_modules, the CLI binary name, an external GitHub user, and four npm package names (npm names must be lowercase). Each was caught and restored.

New tests cover the compat guarantee — the rest of the suite was mechanically renamed, so without them it would have had zero coverage.

2. Docs (`6b10e46`)

43 canonical pages, authored rather than translated — the Python originals are Python prose with Python samples, so nothing was copyable. Every snippet is TS against this SDK's real API, mined from the six pages being replaced.

frameworks/ deviates from the canonical set on purpose: drops claude-agent-sdk (no such wrapper here), adds vercel-ai, a JavaScript-only bridge with no Java or Python counterpart. Recorded in documentation-parity.md.

agent-schema.json is a real draft-07 contract, not a placeholder — it validates all 19 e2e/_configs/ fixtures.

19 stubs, not deletions, so inbound links from npm, issues, and blog posts keep resolving. METRICS.md and LEASE_EXTENSION.md content was migrated in full before stubbing, and their nine inbound references repointed. CHANGELOG.md was left alone — it records what shipped under the old paths.

Also fixes five pre-existing broken README links to docs/api-reference/*-client.md files that never existed, which would have failed the new link check.

3. CI (`bd2c875`)

This repo had no documentation gate — none of the five workflows referenced .md, lychee, or a link checker. Adds Java's three checks in this repo's idiom (a Node verify:* script, not pytest), as one fast job rather than three redundant runs across the Node matrix.

A genuine conflict surfaced: Java's CI greps to reject docs/agents/api-reference.md, while Python keeps it as a stub. We follow Python — preserving inbound links to a public SDK's docs wins — so that pattern is omitted. The retired-reference check is also split in two, because a single blanket grep failed on upgrading.md, whose job is to document the old names.

Verification

Everything below was run, not assumed:

Check	Result
Lint	0 errors, 358 warnings — identical to `main`
Unit tests	1582 pass / 80 suites (was 1569 / 79)
`tsc --noEmit`	Zero net new errors vs `main` (diffed; the 455 pre-existing `e2e/` errors are unchanged)
Build + `verify:dist`	6 entrypoints, ESM + CJS
lychee	506 links, 0 errors
Schema verifier	19 configs + 8 invariants; negative-tested 3 ways
Alias behavior	Verified at runtime against built `dist/`
Internal links	487/487 resolve

Notes for the reviewer

This is one breaking release across 349 files. The docs and rebrand have no technical dependency on each other; they're bundled per an explicit scoping decision. Review commit-by-commit — 2a613f8 is mostly mechanical, 6b10e46 is prose, bd2c875 is 40 lines of YAML plus a script.
CHANGELOG.md retains AGENTSPAN_* in historical entries. Intentional.
docs/agents/getting-started.md documented AGENTSPAN_API_KEY, which no shipped code reads. Dropped from the new docs rather than implemented — if it's meant to work, that's a separate fix.
REVIEW.md (529 lines) is a stale code-review artifact, left in place as out of scope.

🤖 Generated with Claude Code

@deprecated

The agent layer was merged in from the Agentspan TS SDK, which has since been rebranded to Conductor. This aligns the naming with the Python and Java SDKs (conductor-oss/python-sdk#441 did the same). Renamed: - AGENTSPAN_* env vars -> CONDUCTOR_AGENT_* (18 distinct names, 189 files) - AgentspanError -> ConductorAgentError (base of 12 subclasses) - AgentspanMetadata -> ConductorAgentMetadata (langchain/langgraph wrappers) - Stripped 15 "Copyright (c) 2025 Agentspan" headers, as Python did Backward compatibility (the PR description upstream claims env aliases were kept; they were not -- Python deleted every AGENTSPAN_* read. We keep them): - AGENTSPAN_* still resolves as a deprecated fallback beneath CONDUCTOR_AGENT_*, warning once per name per process - AgentspanError / AgentspanMetadata stay exported as @deprecated aliases. The error alias is the same class object, not a subclass, so instanceof works in both directions - 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 -- that suite ships as a release bundle, and the SDK-level alias does not cover vars the harness reads directly Spec R3 precedence gains one tier and is otherwise unchanged: CONDUCTOR_* env -> explicit config -> CONDUCTOR_AGENT_* env -> AGENTSPAN_* env (deprecated) -> http://localhost:8080 Names deliberately left alone, because they are not ours to rename -- renaming them points users at flags that do not exist or breaks interop. Full table in AGENTS.md: - cross-SDK wire keys, all underscore-prefixed: __agentspan_ctx__, __agentspan_sdk__.cjs, _agentspan.llm/.model/.framework/.tools, _agentspan_human_task/_prompt. Same server compile path as Python. - orkes-conductor boot properties: agentspan.embedded, agentspan.default-context-window - external repos, scopes, images: agentspan-ai/agentspan, agentspan-ai/codingexamples, @agentspan-ai, agentspan-server - the external CLI: the `agentspan` binary, ~/.agentspan/config.json, agentspan_linux_amd64, and agentspan deploy/credentials/login/import - version-qualified product references: agentspan <= 0.4.2, agentspan server > 0.4.2 -- renaming these makes them factually false - CHANGELOG.md history, which records what shipped under the old names Tests: adds src/agents/__tests__/legacy-env.test.ts and four spec R3 cases covering the fallback, precedence, warn-once behaviour, and alias identity. The rest of the suite was mechanically renamed, so without these the compat guarantee would have no coverage at all. Verified: 0 lint errors (358 warnings, unchanged from main), 1582 unit tests across 80 suites pass, build + verify:dist clean, and zero net new tsc errors against main. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Ports the layout established in conductor-oss/java-sdk and adopted by conductor-oss/python-sdk#441: docs/*.md plus docs/agents/{concepts,frameworks,reference}/. The 43 canonical pages are authored for TypeScript, not translated. The Python originals are Python prose with Python samples, so nothing was copyable -- every snippet here is TS against this SDK's actual API, mined from the six docs/agents pages being replaced. Authored (43): - docs/README.md index, organized by goal - 20 core guides server-setup, connection-authentication, core-quickstart, workflows, workflow-lifecycle, workers, reliability, observability, api-map, security, debugging, deployment-scaling, schedules-events, schema-client, workflow-testing, compatibility, upgrading, examples, documentation-standard, documentation-parity - docs/agents/concepts/ (11) agents, tools, multi-agent, guardrails, termination, callbacks, streaming-hitl, structured-output, scheduling, stateful, deploy-serve-run - docs/agents/frameworks/ (5) openai, google-adk, langchain, langgraph, vercel-ai - docs/agents/reference/ (6) api, runtime, client, agent-definition, agent-schema.md, agent-schema.json frameworks/ deviates from the canonical set deliberately: drops claude-agent-sdk (no such wrapper here) and adds vercel-ai, which is a JavaScript-only bridge with no Java or Python counterpart. Recorded in documentation-parity.md. Follows Python's documentation-standard verbatim -- "Conductor agents" as the noun, "Conductor-agent" hyphenated only attributively, an Audience line and Prerequisites on every page, goal/guide/result tables -- so the three sets stay diffable. agent-schema.json is a real draft-07 contract, not a placeholder: it validates all 19 fixtures in e2e/_configs/ (checked in the next commit's CI job). Stubs, not deletions (19), so inbound links from npm, issues, and blog posts keep resolving: - docs/agents/{getting-started,writing-agents,advanced,api-reference, framework-agents}.md -> their split replacements - docs/api-reference/*.md (11) -> api-map.md - METRICS.md -> docs/observability.md - LEASE_EXTENSION.md -> docs/reliability.md Java's CI greps to reject docs/agents/api-reference.md as retired while Python keeps it as a stub. We follow Python -- preserving inbound links to a public SDK's docs wins -- so the next commit's grep omits that pattern. METRICS.md and LEASE_EXTENSION.md content was migrated in full before stubbing (metric catalogs, labels, implementation notes, LeaseTracker usage, Python parity table), and their nine inbound references across README/SDK_DEVELOPMENT/SDK_NEW_LANGUAGE_GUIDE/SDK_COMPARISON/ WORKER_ARCHITECTURE_COMPARISON were repointed. CHANGELOG references were left alone -- it records what shipped under the old paths. Also fixes five pre-existing broken links in README.md, which pointed at docs/api-reference/{authorization,secret,prompt,integration,schema}-client.md -- files that never existed. They would have failed the link check added in the next commit. AGENTS.md's Documentation Maintenance contract now points at docs/observability.md, and gains a note that the stubs are deliberate. Verified: all 487 internal markdown links resolve. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

This repo had no documentation gate at all -- none of the five workflows referenced .md, lychee, a link checker, or markdownlint. Adds the three checks java-sdk runs in ci.yml, in this repo's idiom. One fast `docs` job rather than folding these into the unit-test matrix: there they would run three times identically across Node 20/22/24, and link checking would depend on network state inside a unit-test run. 1. Link validation -- lycheeverse/lychee-action, same args as java-sdk (`--offline --no-progress README.md docs`). 2. Retired-reference grep, split into two steps because one pattern could not serve both purposes: - retired paths and renderer-specific constructs, unconditional - AGENTSPAN_* outside the migration guide, with upgrading.md and compatibility.md excluded The second exists because docs/upgrading.md must show the old names to document the rename; a single blanket grep failed on its own migration guide. Deliberately omits java-sdk's docs/agents/api-reference.md and docs/agents/index.md patterns -- we keep those as redirect stubs, as python-sdk does. See docs/documentation-parity.md. 3. Agent configuration schema -- scripts/verify-agent-schema.mjs, wired as `npm run verify:agent-schema`, following the existing verify-dist.mjs pattern rather than transliterating python-sdk's pytest approach. Validates docs/agents/reference/agent-schema.json against all 19 fixtures in e2e/_configs/, then asserts 8 structural invariants (name required and identifier-patterned, additionalProperties stays permissive so a newer server field cannot break an older SDK, agents recursive, toolType enum includes worker, all nine strategies present, guardrail onFail complete, handoff target required) and the canonical documentation paths. Adds ajv ^8.17.1 as an explicit devDependency. It was already present transitively via eslint, but depending on a transitive dep for a CI gate is how gates silently stop running. Verified locally, not just assumed: lychee reports 506 links / 0 errors; both greps are clean; the schema verifier passes and was negative-tested three ways (a config missing `name`, a name violating the identifier pattern, and a forbidden path reappearing) -- each fails as intended and returns to green. Workflow YAML parses with all 7 steps. Lint 0 errors, 1582 unit tests pass. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

main advanced four commits while this branch was in flight (#141, #142 touched agent examples). Two files gained AGENTSPAN_* references after the rename sweep had already run, so they still told readers to set the deprecated names: - SDK_DEVELOPMENT.md:623 - examples/README.md:51-52 Both are outside the `README.md docs` scope the new CI grep covers, so they would not have been caught. Worth noting the grep itself is correctly calibrated: it matches AGENTSPAN_[A-Z] (a concrete variable name) and so does not fire on the `AGENTSPAN_*` glob that the migration and reference pages legitimately use. Also resolves the rebase conflict in examples/agents/README.md, taking main's table shape from #142 (example counts removed) with this branch's "Conductor Quickstart" rename applied. The `agentspan deploy` CLI invocation in that file is left as-is -- external command surface. Re-verified post-rebase: lint 0 errors (358 warnings, unchanged), 1582 unit tests across 80 suites, lychee 508 links / 0 errors, schema verifier green, 649 internal markdown links resolve. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

The rebrand sweep rewrote `chmod +x agentspan` to `chmod +x Conductor`, breaking the Agent E2E workflow at the "Download CLI binary from release" step: chmod: cannot access 'Conductor': No such file or directory The downloaded artifact is named `agentspan` -- it is the external CLI's binary, not ours. `--output agentspan` on the line above was in the protected set, but the bare binary name on the next line was not, so the lowercase prose rule caught it. Found by CI, not by the local audit, which checked quoted string literals and URL/scope positions but not bare shell command arguments. Swept the same class across .github/workflows/, scripts/, and e2e/ for `Conductor` in a command position -- no other instances. Also corrects the surrounding comments, which the sweep had left calling this the "Conductor CLI" while the command downloads `agentspan_linux_amd64` and chmods `agentspan`. Prose that disagrees with the literal beside it is the specific failure mode this rebrand was supposed to avoid, so these now say "external `agentspan` CLI". Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

codecov · 2026-07-29T02:03:44Z

Codecov Report

✅ All modified and coverable lines are covered by tests.

Flag	Coverage Δ
integration-v4-sm	`41.42% <ø> (-0.05%)`	⬇️
integration-v5-sdkdev	`43.88% <ø> (-0.04%)`	⬇️
unit	`73.95% <ø> (+0.11%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.
see 9 files 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.

Two leftovers from the rebrand sweep, both cosmetic but wrong: 1. "an Agentspan" became "an Conductor" in three doc comments (src/agents/worker.ts, src/agents/skill.ts, src/sdk/clients/agent/WorkflowClient.ts). The article no longer agrees. 2. Seven files carried `Copyright (c) 2026 Agentspan` headers, which the sweep renamed to "2026 Conductor" rather than removing. The 15 files with `2025 Agentspan` headers were stripped, matching what python-sdk did, so these were inconsistent -- and asserting a "Conductor" copyright holder is a claim this change has no business making. Only 7 of ~700 source files had a header at all, so stripping matches the repo norm too. No behavior change. src/ now carries no copyright headers. Verified: lint 0 errors (358 warnings, unchanged from origin/main), 1582 unit tests across 80 suites, schema verifier green, lychee 0 errors, and tsc has zero net new errors against origin/main -- 455 pre-existing on both sides, the single diff being one error line-shifted 15 -> 12 by the header strip. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

ambiorix2099 · 2026-07-29T15:57:06Z

Superseded. #147 merged the docs restructure and the rebrand while this was in flight, and main now carries all 63 doc files this PR authored (plus docs/workflow-message-queue.md) and a stricter lychee check.

Two things from here were not covered by #147, and are now split out into a focused PR:

Backward compatibility. Align javascript-sdk docs with the java-sdk/python-sdk documentation-parity standard #147 removed the AGENTSPAN_* names with no aliases, and two of the three failure modes are silent — AGENTSPAN_SERVER_URL in particular is no longer read at all, so an existing deployment falls through to http://localhost:8080.
Schema validation. docs/agents/reference/agent-schema.json ships as a documented cross-SDK contract with nothing checking it against the serializer.

See #151. Full original work preserved on the backup/full-work-148 branch if any of the authored prose is worth salvaging.

ambiorix2099 and others added 4 commits July 28, 2026 18:58

ambiorix2099 force-pushed the docs/align-with-java-doc-structure branch from bd2c875 to d747352 Compare July 29, 2026 01:59

ambiorix2099 closed this Jul 29, 2026

ambiorix2099 mentioned this pull request Jul 29, 2026

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

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Align JavaScript SDK documentation with the Java SDK's structure and Conductor-agent terminology - #148

Align JavaScript SDK documentation with the Java SDK's structure and Conductor-agent terminology#148
ambiorix2099 wants to merge 6 commits into
mainfrom
docs/align-with-java-doc-structure

ambiorix2099 commented Jul 29, 2026

Uh oh!

codecov Bot commented Jul 29, 2026 •

edited

Loading

Uh oh!

ambiorix2099 commented Jul 29, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

ambiorix2099 commented Jul 29, 2026

The premise was verified first, and it holds here

1. Rebrand (2a613f8)

2. Docs (6b10e46)

3. CI (bd2c875)

Verification

Notes for the reviewer

Uh oh!

codecov Bot commented Jul 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

ambiorix2099 commented Jul 29, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

1. Rebrand (`2a613f8`)

2. Docs (`6b10e46`)

3. CI (`bd2c875`)

codecov Bot commented Jul 29, 2026 •

edited

Loading