feat: extract @wraith-protocol/sdk-agent companion package (#185)

[lamborghini21]

Extracts agent functionality (Wraith, WraithAgent, Chain, Claude tools) into a separate @wraith-protocol/sdk-agent package to reduce root bundle size and improve API surface. Root package now provides deprecated compatibility shims for backward compatibility.

• Create packages/sdk-agent/ with client.ts, tools.ts, types.ts
• Move agent tests to packages/sdk-agent/test/
• Update examples to use new @wraith-protocol/sdk-agent package
• Add compatibility shims in src/agent/ with deprecation warnings
• Update root package.json exports to include agent entry point
• Configure tsup to mark @wraith-protocol/sdk-agent as external
• Add README for sdk-agent package with adapter shape documentation

Closes #185

[drips-wave]

@lamborghini21 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[truthixify]

Thanks @lamborghini21. Same gate as a few other PRs this wave: test (20) and test (22) fail on pnpm api:check, not on a test.

Moving src/agent/ out to packages/sdk-agent/ changes what the root entry exports, which is exactly the kind of change the api-extractor baseline exists to catch, so it needs regenerating:

pnpm build
git add etc/
git commit -m "chore: refresh api-extractor baseline"
git push

Given this PR is specifically about shrinking the root bundle, it is worth eyeballing the regenerated etc/sdk.api.md diff rather than just committing it. The agent symbols should be leaving the root surface, and if they are still there the compatibility shim is re-exporting more than intended.

[lamborghini21]

Thanks @lamborghini21. Same gate as a few other PRs this wave: test (20) and test (22) fail on pnpm api:check, not on a test.

Moving src/agent/ out to packages/sdk-agent/ changes what the root entry exports, which is exactly the kind of change the api-extractor baseline exists to catch, so it needs regenerating:

pnpm build
git add etc/
git commit -m "chore: refresh api-extractor baseline"
git push

Given this PR is specifically about shrinking the root bundle, it is worth eyeballing the regenerated etc/sdk.api.md diff rather than just committing it. The agent symbols should be leaving the root surface, and if they are still there the compatibility shim is re-exporting more than intended.

Thank you for the insight.

Please check once again.

[truthixify]

Went conflicted just now because #191 and #192 landed ahead of it. Nothing wrong with your work, it was mergeable minutes ago.

git fetch origin
git rebase origin/develop

I checked the api surface diff before the conflict appeared and the agent symbols do leave the root, so the extraction is doing what it should rather than just re-exporting.

[lamborghini21]

Went conflicted just now because #191 and #192 landed ahead of it. Nothing wrong with your work, it was mergeable minutes ago.

git fetch origin
git rebase origin/develop

I checked the api surface diff before the conflict appeared and the agent symbols do leave the root, so the extraction is doing what it should rather than just re-exporting.

okay

[truthixify]

I attempted to rebase this for you and backed out, because the conflict is a real port rather than a text merge. Nothing was pushed, your branch is untouched.

src/agent/tools.ts is the problem. #191 landed OpenTelemetry instrumentation while this was open, so develop's copy of that file now imports withSpan and Tracer from src/telemetry and carries a tracer? field on ClaudeAgentToolContext. Your PR moves that same file out to packages/sdk-agent/.

Resolving it means deciding how the extracted package gets at the core's telemetry: whether @wraith-protocol/sdk-agent takes a dependency on the core for Tracer, re-exports its own, or accepts one by injection. That is a design decision about your package boundary and I did not want to pick for you.

src/index.ts is easier: keep the wallet-adapter and telemetry exports that landed from #186 and #191, drop only the agent ones. pnpm-lock.yaml and etc/sdk.api.md you can regenerate rather than merge by hand, with pnpm install and pnpm build.

Happy to pair on the telemetry boundary question if it is easier to talk through than to write out.

[lamborghini21]

I attempted to rebase this for you and backed out, because the conflict is a real port rather than a text merge. Nothing was pushed, your branch is untouched.

src/agent/tools.ts is the problem. #191 landed OpenTelemetry instrumentation while this was open, so develop's copy of that file now imports withSpan and Tracer from src/telemetry and carries a tracer? field on ClaudeAgentToolContext. Your PR moves that same file out to packages/sdk-agent/.

Resolving it means deciding how the extracted package gets at the core's telemetry: whether @wraith-protocol/sdk-agent takes a dependency on the core for Tracer, re-exports its own, or accepts one by injection. That is a design decision about your package boundary and I did not want to pick for you.

src/index.ts is easier: keep the wallet-adapter and telemetry exports that landed from #186 and #191, drop only the agent ones. pnpm-lock.yaml and etc/sdk.api.md you can regenerate rather than merge by hand, with pnpm install and pnpm build.

Happy to pair on the telemetry boundary question if it is easier to talk through than to write out.

okay, checking out

[truthixify]

Thanks @lamborghini21, you answered the boundary question: packages/sdk-agent takes @wraith-protocol/sdk as a workspace:* dependency. That is the right of the three options I listed.

One thing to fix before this lands, though, because the current shape quietly breaks telemetry.

packages/sdk-agent/src/tools.ts imports the crypto functions from @wraith-protocol/sdk/chains/stellar, but then re-declares Tracer and withSpan locally (lines 12 and 20) instead of importing them from the core, which already exports setTracer, getTracer, withSpan and NOOP_TRACER since #191.

The consequence is that there are now two independent tracer registries. A user who does this:

import { setTracer } from '@wraith-protocol/sdk';
setTracer(otelAdapter);

will get spans from scanning and RPC, and no spans from agent tool calls, because your local withSpan never consults the core's global tracer. It only uses a tracer passed explicitly through ClaudeAgentToolContext. Structural typing means it will not error, it will just silently emit nothing, which is the worst failure mode for observability.

Since the package already depends on the core, the fix is to delete the local declarations and import instead:

import { withSpan, type Tracer } from '@wraith-protocol/sdk';

On the remaining conflicts: etc/sdk.api.md and pnpm-lock.yaml should be regenerated rather than merged by hand (pnpm install && pnpm build). src/agent/tools.ts conflicts because develop's copy picked up the OTel instrumentation while your branch deletes the file, so take the deletion. packages/sdk-agent/test/tools.test.ts is the only one needing real attention.

Worth eyeballing the regenerated etc/sdk.api.md too, since the whole point of this PR is shrinking the root surface: the agent symbols should be leaving it.

[lamborghini21]

Thanks @lamborghini21, you answered the boundary question: packages/sdk-agent takes @wraith-protocol/sdk as a workspace:* dependency. That is the right of the three options I listed.

One thing to fix before this lands, though, because the current shape quietly breaks telemetry.

packages/sdk-agent/src/tools.ts imports the crypto functions from @wraith-protocol/sdk/chains/stellar, but then re-declares Tracer and withSpan locally (lines 12 and 20) instead of importing them from the core, which already exports setTracer, getTracer, withSpan and NOOP_TRACER since #191.

The consequence is that there are now two independent tracer registries. A user who does this:

import { setTracer } from '@wraith-protocol/sdk';
setTracer(otelAdapter);

will get spans from scanning and RPC, and no spans from agent tool calls, because your local withSpan never consults the core's global tracer. It only uses a tracer passed explicitly through ClaudeAgentToolContext. Structural typing means it will not error, it will just silently emit nothing, which is the worst failure mode for observability.

Since the package already depends on the core, the fix is to delete the local declarations and import instead:

import { withSpan, type Tracer } from '@wraith-protocol/sdk';

On the remaining conflicts: etc/sdk.api.md and pnpm-lock.yaml should be regenerated rather than merged by hand (pnpm install && pnpm build). src/agent/tools.ts conflicts because develop's copy picked up the OTel instrumentation while your branch deletes the file, so take the deletion. packages/sdk-agent/test/tools.test.ts is the only one needing real attention.

Worth eyeballing the regenerated etc/sdk.api.md too, since the whole point of this PR is shrinking the root surface: the agent symbols should be leaving it.

Noted. I will work on it

[lamborghini21]

@truthixify

[truthixify]

Merged @lamborghini21. Both points from the last review are fixed: packages/sdk-agent/src/tools.ts now imports withSpan and Tracer from @wraith-protocol/sdk instead of re-declaring them, so there is one tracer registry rather than two and setTracer() on the core actually reaches agent tool calls.

The regenerated etc/sdk.api.md confirms the extraction did what it was supposed to: Wraith, WraithAgent, Chain, AgentConfig and AgentInfo are all gone from the root surface. That was the whole point of #185, so good to see it verified rather than assumed.

Thanks for working through three rounds on this one, including a rebase over a moving target after #191 landed telemetry into the file you were extracting.