Background
PR #48 split the TypeScript SDK into @synadia-ai/agents (caller, in client-sdk/typescript/) and @synadia-ai/agent-service (host, in agent-sdk/typescript/). The ReferenceAgent class moved cleanly to agent-sdk/typescript/src/testing/reference-agent.ts — but the runnable wrapper script _run-reference-agent.ts stayed behind in client-sdk/typescript/examples/.
To keep that wrapper compiling, @synadia-ai/agent-service was added to client-sdk/typescript/devDependencies as a file:../../agent-sdk/typescript link. So the caller-side package has a build-time dependency on the host-side package — present only to support one demo wrapper.
The Python side already has the cleaner pattern:
|
TS (today) |
Python (today) |
| Reference agent class |
agent-sdk/typescript/src/testing/reference-agent.ts ✓ |
agent-sdk/python/src/... ✓ |
| Runnable wrapper |
client-sdk/typescript/examples/_run-reference-agent.ts ⚠ |
agent-sdk/python/examples/_reference_agent.py ✓ |
| Cross-package devDep needed? |
Yes (@synadia-ai/agent-service in client-sdk's devDeps) |
No |
client-sdk/python/examples/README.md just tells users to run the agent from the sibling directory (uv run --directory ../../agent-sdk/python python examples/_reference_agent.py …), with no Python-side dep on the agent-sdk package.
Now that the npm packages are actually published, this is a good moment to mirror that layout on TS.
Proposed change
git mv client-sdk/typescript/examples/_run-reference-agent.ts agent-sdk/typescript/examples/_run-reference-agent.ts (creates the examples/ dir on agent-sdk, which doesn't exist yet).- Drop
@synadia-ai/agent-service from client-sdk/typescript/devDependencies and refresh client-sdk/typescript/bun.lock.
- Make sure
agent-sdk/typescript/package.json has whatever it needs to run examples (probably @nats-io/transport-node is already there as a devDep — confirm).
- Update inline references to the old path:
client-sdk/typescript/examples/03-prompt-attachment.ts:14 (comment header points readers at bun run examples/_run-reference-agent.ts).- Other
01..05-*.ts example file headers — sweep for the same pattern.
client-sdk/typescript/README.md quickstart / examples section, if it shows the old path.
- Update top-level docs:
README.md:47 (TypeScript row of the "Reference agents and demo scripts" table — currently links to client-sdk/typescript/examples/_run-reference-agent.ts).CLAUDE.md:35 (Reference agents — canonical implementations §, TypeScript bullet).
- Mirror the Python invocation pattern in the docs: from
client-sdk/typescript/, running the demos becomes a two-terminal flow with the agent invoked as bun --cwd ../../agent-sdk/typescript examples/_run-reference-agent.ts (or whatever the cleanest Bun equivalent is — Mario knows the toolchain better).
- CI: confirm
client-sdk-typescript.yml and agent-sdk-typescript.yml still pass — both already trigger on changes under either subtree, so the move shouldn't need workflow changes, but worth verifying.
Why now
@synadia-ai/agents@0.4.0 and @synadia-ai/agent-service@0.4.0 are now published, so any ^0.4.x consumers stay unaffected by an internal layout move (no new published exports, no breakage).- The current backward devDep (
client-sdk → agent-sdk via file: link) is the kind of pre-split inertia worth cleaning up before the next release goes out.
Out of scope
- No changes to the public API of either package.
- No changes to the
ReferenceAgent class itself or the @synadia-ai/agent-service/testing subpath.
- No CHANGELOG entry under
@synadia-ai/agents (it's purely internal — caller-side consumers see no change). One-line under agent-sdk/typescript/CHANGELOG.md [Unreleased] noting the wrapper now ships alongside the host package.
Context for whoever picks this up
Background
PR #48 split the TypeScript SDK into
@synadia-ai/agents(caller, inclient-sdk/typescript/) and@synadia-ai/agent-service(host, inagent-sdk/typescript/). TheReferenceAgentclass moved cleanly toagent-sdk/typescript/src/testing/reference-agent.ts— but the runnable wrapper script_run-reference-agent.tsstayed behind inclient-sdk/typescript/examples/.To keep that wrapper compiling,
@synadia-ai/agent-servicewas added toclient-sdk/typescript/devDependenciesas afile:../../agent-sdk/typescriptlink. So the caller-side package has a build-time dependency on the host-side package — present only to support one demo wrapper.The Python side already has the cleaner pattern:
agent-sdk/typescript/src/testing/reference-agent.ts✓agent-sdk/python/src/...✓client-sdk/typescript/examples/_run-reference-agent.ts⚠agent-sdk/python/examples/_reference_agent.py✓@synadia-ai/agent-servicein client-sdk's devDeps)client-sdk/python/examples/README.mdjust tells users to run the agent from the sibling directory (uv run --directory ../../agent-sdk/python python examples/_reference_agent.py …), with no Python-side dep on the agent-sdk package.Now that the npm packages are actually published, this is a good moment to mirror that layout on TS.
Proposed change
git mv client-sdk/typescript/examples/_run-reference-agent.ts agent-sdk/typescript/examples/_run-reference-agent.ts(creates theexamples/dir on agent-sdk, which doesn't exist yet).@synadia-ai/agent-servicefromclient-sdk/typescript/devDependenciesand refreshclient-sdk/typescript/bun.lock.agent-sdk/typescript/package.jsonhas whatever it needs to run examples (probably@nats-io/transport-nodeis already there as a devDep — confirm).client-sdk/typescript/examples/03-prompt-attachment.ts:14(comment header points readers atbun run examples/_run-reference-agent.ts).01..05-*.tsexample file headers — sweep for the same pattern.client-sdk/typescript/README.mdquickstart / examples section, if it shows the old path.README.md:47(TypeScript row of the "Reference agents and demo scripts" table — currently links toclient-sdk/typescript/examples/_run-reference-agent.ts).CLAUDE.md:35(Reference agents — canonical implementations §, TypeScript bullet).client-sdk/typescript/, running the demos becomes a two-terminal flow with the agent invoked asbun --cwd ../../agent-sdk/typescript examples/_run-reference-agent.ts(or whatever the cleanest Bun equivalent is — Mario knows the toolchain better).client-sdk-typescript.ymlandagent-sdk-typescript.ymlstill pass — both already trigger on changes under either subtree, so the move shouldn't need workflow changes, but worth verifying.Why now
@synadia-ai/agents@0.4.0and@synadia-ai/agent-service@0.4.0are now published, so any^0.4.xconsumers stay unaffected by an internal layout move (no new published exports, no breakage).client-sdk→agent-sdkviafile:link) is the kind of pre-split inertia worth cleaning up before the next release goes out.Out of scope
ReferenceAgentclass itself or the@synadia-ai/agent-service/testingsubpath.@synadia-ai/agents(it's purely internal — caller-side consumers see no change). One-line underagent-sdk/typescript/CHANGELOG.md[Unreleased] noting the wrapper now ships alongside the host package.Context for whoever picks this up
docs/split-sdk-sweep).client-sdk/python/examples/README.mdlines ~20-35 for the wording pattern (telling readers to run the agent from the sibling agent-sdk directory).