docs(examples): sandbox-stream-backend uses the real sandbox-SDK SandboxEvent shape (post-#36)#37
Merged
Conversation
…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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Follow-up to #36 (closes #35).
The
sandbox-stream-backendexample 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.updatedwith nesteddata.part.text) — which is what consumers using the real@tangle-network/sandboxSDK actually hit, and which was the exact gap #36 fixed.This PR rewrites the example to emit the canonical sandbox-SDK shape verbatim:
…and demonstrates that
createSandboxPromptBackendwith nomapEventshim produces the full canonical RuntimeStreamEvent stream out of the box. Header + inline comments call out:mapEventis optional (only for product-specific event types outside the documented vocabulary),data.part.textnatively (closes #35) #36).Verification
pnpm exec tsx examples/sandbox-stream-backend/sandbox-stream-backend.tsemits 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 runspnpm run lint,pnpm test,pnpm typecheck— all green.