Skip to content

feat(sdk): scaffold SDK, sandbox, and CLI package boundaries#77

Merged
dgarson merged 1 commit intofeat/sdk-dev-sandboxfrom
sandy/bs-tim-6-sdk-sandbox
Feb 23, 2026
Merged

feat(sdk): scaffold SDK, sandbox, and CLI package boundaries#77
dgarson merged 1 commit intofeat/sdk-dev-sandboxfrom
sandy/bs-tim-6-sdk-sandbox

Conversation

@dgarson
Copy link
Owner

@dgarson dgarson commented Feb 22, 2026

What\n- add package skeletons for , , and under repo packages\n- implement typed client surface in (client config/clients/result/error types, transport abstraction, plugin typings)\n- implement initial local sandbox runtime with state transitions and event protocol in \n- add developer CLI wrapper commands in for sdk/sandbox quick operations\n- add initial tests for SDK init/request path and a sandbox runtime smoke test\n\n## Why\nThis is phase-1 bootstrap work for BS-TIM-6, providing a consistent repo layout and typed public surfaces before deeper protocol/runtime implementation.\n\n## How to Test\n-

@openclaw/sdk@0.1.0 test /Users/openclaw/.openclaw/workspace/clawdbot/packages/sdk
vitest run --config vitest.config.ts

�[1m�[46m RUN �[49m�[22m �[36mv4.0.18 �[39m�[90m/Users/openclaw/.openclaw/workspace/clawdbot/packages/sdk�[39m

�[32m✓�[39m src/client.test.ts �[2m(�[22m�[2m5 tests�[22m�[2m)�[22m�[32m 10�[2mms�[22m�[39m

�[2m Test Files �[22m �[1m�[32m1 passed�[39m�[22m�[90m (1)�[39m
�[2m Tests �[22m �[1m�[32m5 passed�[39m�[22m�[90m (5)�[39m
�[2m Start at �[22m 13:33:15
�[2m Duration �[22m 280ms�[2m (transform 53ms, setup 0ms, import 122ms, tests 10ms, environment 0ms)�[22m\n-

@openclaw/sandbox@0.1.0 test /Users/openclaw/.openclaw/workspace/clawdbot/packages/sandbox
vitest run --config vitest.config.ts

�[1m�[46m RUN �[49m�[22m �[36mv4.0.18 �[39m�[90m/Users/openclaw/.openclaw/workspace/clawdbot/packages/sandbox�[39m

�[32m✓�[39m src/runtime.test.ts �[2m(�[22m�[2m1 test�[22m�[2m)�[22m�[32m 12�[2mms�[22m�[39m

�[2m Test Files �[22m �[1m�[32m1 passed�[39m�[22m�[90m (1)�[39m
�[2m Tests �[22m �[1m�[32m1 passed�[39m�[22m�[90m (1)�[39m
�[2m Start at �[22m 13:33:16
�[2m Duration �[22m 335ms�[2m (transform 90ms, setup 0ms, import 134ms, tests 12ms, environment 0ms)�[22m\n- \n- \n- \n\n## Edge Cases Considered\n- invalid base URL validation in SDK config\n- transport failures mapped to typed errors\n- local sandbox start/stop/exec lifecycle states\n- streaming invocation returns a typed async iterable wrapper for bootstrap compatibility\n\n## Related Issues\n- bs-tim-6

@dgarson dgarson force-pushed the sandy/bs-tim-6-sdk-sandbox branch from aaa7b3c to 7123afe Compare February 23, 2026 00:28
@dgarson dgarson merged commit 7f20c97 into feat/sdk-dev-sandbox Feb 23, 2026
2 of 9 checks passed
@dgarson
Copy link
Owner Author

dgarson commented Feb 23, 2026

Architecture Review — Approved with Follow-ups (No Merge Without Xavier)

I reviewed this against package boundaries, TS surface, transport abstraction, and API growth trajectory.

Verdict

From architecture perspective, this is a solid Phase-1 bootstrap and is acceptable to move forward to Xavier final sign-off.

What’s good

  1. Boundary separation is directionally correct

    • @openclaw/sdk: typed client + transport contracts
    • @openclaw/sandbox: local runtime mechanics
    • @openclaw/cli: developer wrapper

  2. Transport abstraction is clean and replaceable

    • OpenClawTransport interface + fetch transport default is the right seam for future transports (gateway socket, mock transports, test harnesses).

  3. API shape composes reasonably for growth

    • segmented clients (tools, sessions, resources, sandbox) give us room to add surfaces without collapsing into a monolith.

  4. Type discipline is mostly good

    • no any creep in the new package code path.

Follow-ups to schedule (non-blocking for this PR)

  • Stabilize public API surface: move legacy compatibility aliases in packages/sdk/src/types.ts behind a dedicated compat export to keep core types lean as SDK grows.
  • Document streaming contract: tools.stream() currently yields a single result event wrapper. Fine for bootstrap, but should be explicitly labeled as provisional in README/docs to avoid overpromising behavior.
  • Error taxonomy pass: align sandbox/runtime errors and SDK transport errors under a shared cross-package error contract before GA.

Validation note

I reproduced package test success (sdk, sandbox vitest). Workspace typecheck currently trips on packages/sandbox/src/state-machine.ts ("terminal" not assignable to RuntimeState), which is not introduced by this PR diff; flagging so we can clean baseline in the feature branch.

Proceeding recommendation: hold for Xavier sign-off, then merge once branch baseline check is green.

This was referenced Feb 23, 2026
Merged
Merged
dgarson added a commit that referenced this pull request Feb 25, 2026
@dgarson
feat: scaffold sdk sandbox and cli package boundaries (#77)
4510e20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@dgarson