Skip to content

docs(examples): sandbox-stream-backend uses the real sandbox-SDK SandboxEvent shape (post-#36)#37

Merged
drewstone merged 1 commit into
mainfrom
feat/sandbox-stream-example-real-shape
May 23, 2026
Merged

docs(examples): sandbox-stream-backend uses the real sandbox-SDK SandboxEvent shape (post-#36)#37
drewstone merged 1 commit into
mainfrom
feat/sandbox-stream-example-real-shape

Conversation

@drewstone

Copy link
Copy Markdown
Contributor

Follow-up to #36 (closes #35).

The sandbox-stream-backend example previously dodged the load-bearing question by emitting flat { type: 'text_delta', text } — which the default mapper trivially passes through. That was hiding the actual sandbox-SDK event shape (message.part.updated with nested data.part.text) — which is what consumers using the real @tangle-network/sandbox SDK actually hit, and which was the exact gap #36 fixed.

This PR rewrites the example to emit the canonical sandbox-SDK shape verbatim:

yield { type: 'message.part.updated', data: { part: { type: 'text', text: 'hello\n' } } }
yield { type: 'tool_call',  data: { id: 'call_1', name: 'Read', input: { path: '/tmp/notes.md' } } }
yield { type: 'tool_result', data: { id: 'call_1', name: 'Read', output: '(...)' } }

…and demonstrates that createSandboxPromptBackend with no mapEvent shim produces the full canonical RuntimeStreamEvent stream out of the box. Header + inline comments call out:

Verification

pnpm exec tsx examples/sandbox-stream-backend/sandbox-stream-backend.ts

emits the canonical RuntimeStreamEvent sequence: task_start, readiness_*, session_created, backend_start, text_delta × 3 (the unwrap path #36 added), tool_call, tool_result, backend_end, task_end, final. Tested locally; CI runs pnpm run lint, pnpm test, pnpm typecheck — all green.

…boxEvent shape

The example previously sidestepped the actual sandbox-SDK event shape
by emitting flat `{ type: 'text_delta', text }` — which the default
mapper trivially passes through. That dodged the load-bearing question
products consuming the real SDK actually hit: how does
`createSandboxPromptBackend` handle the canonical shape
`{ type: 'message.part.updated', data: { part: { type: 'text', text } } }`?

After #36 (closes #35), the default `mapCommonBackendEvent` handles
this natively. This example now demonstrates the canonical pattern
verbatim so consumers can copy it into their product code without
guessing:

  - `streamPrompt` yields `SandboxEvent`s (the actual SDK shape).
  - Text deltas arrive as `message.part.updated` with `data.part.text`
    nested — no per-product `mapEvent` shim required.
  - Tool turns arrive as `tool_call` + `tool_result` with `data.name`
    + `data.input` / `data.output` — also handled by the default.

Header comment + inline comments call out exactly which event variants
the default mapper handles, and explicitly note that `mapEvent` is
optional and only needed for product-specific shapes outside the
canonical vocabulary.

Verified by running the example end-to-end:
  pnpm exec tsx examples/sandbox-stream-backend/sandbox-stream-backend.ts
emits the canonical RuntimeStreamEvent sequence — `task_start`,
`readiness_*`, `session_created`, `backend_start`, **`text_delta`** (x3,
from the nested `data.part.text` shape — the bit that was broken
pre-#36), `tool_call`, `tool_result`, `backend_end`, `task_end`,
`final`. The full vocabulary the README documents.
@drewstone drewstone merged commit 0ae98b9 into main May 23, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

createSandboxPromptBackend default mapper doesn't unwrap sandbox-SDK SandboxEvent shape (silent text_delta loss)

1 participant