fix(backends): mapCommonBackendEvent unwraps sandbox-SDK data.part.text natively (closes #35) (#36)

Closes #35.

The canonical `@tangle-network/sandbox` `box.streamTask` emits
`message.part.updated` with the text nested under
`data.part.text`:

  { type: 'message.part.updated', data: { part: { type: 'text', text: '…' } } }

Before this fix, the default `mapCommonBackendEvent` only walked
`data.text` / `data.delta` / `record.text` — sandbox-SDK text deltas
silently dropped out of the canonical stream, forcing every sandbox-SDK
consumer (blueprint-agent#1758, future gtm-agent sandbox path, every
sandbox-hosted product downstream) to ship a duplicated `mapEvent` shim
that walked `data.part.text` themselves.

Fix: the `message.part.updated` branch now ALSO walks `data.part.text`
when `data.part.type === 'text'` (or undefined for forward-compat).
Resolution order is `data.text` → `data.delta` → `record.text` →
`data.part.text` so any consumer already passing the flat shape keeps
working unchanged (covered by the new precedence test).

Two new tests pin the behaviour:

- "unwraps the @tangle-network/sandbox `data.part.text` shape natively"
  — fires the real sandbox-SDK shape through `runAgentTaskStream` and
  asserts the canonical `text_delta` stream contains `['hello', ' world']`,
  plus that a non-text part-kind drops cleanly (does NOT mis-fire as a
  text_delta).
- "prefers explicit `data.text` when both shapes present" —
  back-compat: any existing call site sending `{ data: { text } }` keeps
  winning over the nested shape.

Result: products consuming the sandbox SDK can wire it straight into
`createSandboxPromptBackend` without writing a `mapEvent` shim — the
default does the right thing. Blueprint's pinned contract test
(blueprint-agent#1758, `Claude-Code → RuntimeStreamEvent migration seam`)
that documented this gap as a finding now becomes the regression guard
on this fix.

Verification
────────────
- `pnpm test` — 181/181 pass (+2 new).
- `pnpm typecheck` — clean.

Author: drewstone

src/backends.ts

@@ -299,7 +299,19 @@ function mapCommonBackendEvent(
       ? (record.data as Record<string, unknown>)
       : record
   if (type === 'message.part.updated' || type === 'text_delta' || type === 'delta') {
-    const text = stringValue(data.text) ?? stringValue(data.delta) ?? stringValue(record.text)
+    // `@tangle-network/sandbox` `box.streamTask` emits `message.part.updated`
+    // with a nested part: `{ type: 'message.part.updated', data: { part:
+    // { type: 'text', text: '…' } } }`. Walk into `data.part.text` so the
+    // canonical sandbox-SDK shape produces a `text_delta` natively — no
+    // per-product `mapEvent` shim required. Tool parts are picked up by
+    // the `tool_call` / `tool_result` branches below; non-text parts here
+    // fall through to `undefined` (the consumer can opt in via `mapEvent`).
+    const part = data.part as Record<string, unknown> | undefined
+    const partText =
+      part !== undefined && typeof part === 'object' && (part.type === 'text' || part.type === undefined)
+        ? stringValue(part.text)
+        : undefined
+    const text = stringValue(data.text) ?? stringValue(data.delta) ?? stringValue(record.text) ?? partText
     return text
       ? {
           type: 'text_delta',

tests/runtime.test.ts

@@ -495,6 +495,65 @@ describe('runAgentTask', () => {
     })
   })
 
+  it('unwraps the @tangle-network/sandbox `data.part.text` shape natively (no mapEvent shim needed)', async () => {
+    // The sandbox SDK emits `message.part.updated` with the text nested
+    // under `data.part.text` (the canonical sandbox-SDK shape). Before
+    // this fix, the default mapper looked at `data.text`/`data.delta`
+    // only and silently dropped every part-text event — forcing every
+    // sandbox-SDK consumer to ship a `mapEvent` shim (see blueprint-
+    // agent#1758, tangle-network/agent-runtime#35). This test pins the
+    // native unwrap so a regression here breaks the entire sandbox-SDK
+    // → agent-runtime chat-engine path.
+    const backend = createSandboxPromptBackend({
+      getBox: () => ({ id: 'box-sandbox-sdk' }),
+      getSessionId: (box) => box.id,
+      async *streamPrompt() {
+        yield { type: 'message.part.updated', data: { part: { type: 'text', text: 'hello' } } }
+        yield { type: 'message.part.updated', data: { part: { type: 'text', text: ' world' } } }
+        // A part of a non-text kind should NOT produce a text_delta —
+        // those are handled by the `tool_call`/`tool_result` branches
+        // when the consumer streams the matching event types.
+        yield { type: 'message.part.updated', data: { part: { type: 'tool', name: 'bash' } } }
+      },
+    })
+    const events = await collect(
+      runAgentTaskStream({
+        task: { id: 'sandbox-sdk-shape', intent: 'inspect', requiredKnowledge: [readyReq] },
+        backend,
+        input: { message: 'go' },
+      }),
+    )
+
+    expect(
+      events.filter((event) => event.type === 'text_delta').map((event) => event.text),
+    ).toEqual(['hello', ' world'])
+  })
+
+  it('prefers explicit `data.text` when both `data.text` and `data.part.text` are present (back-compat)', async () => {
+    // If a consumer happens to send both shapes (mixed bag), the flat
+    // `data.text` wins — preserves the pre-existing behaviour for any
+    // call site that was passing `{ data: { text } }` directly.
+    const backend = createSandboxPromptBackend({
+      getBox: () => ({ id: 'box-1' }),
+      async *streamPrompt() {
+        yield {
+          type: 'message.part.updated',
+          data: { text: 'flat-wins', part: { type: 'text', text: 'should-not-win' } },
+        }
+      },
+    })
+    const events = await collect(
+      runAgentTaskStream({
+        task: { id: 'precedence', intent: 'inspect', requiredKnowledge: [readyReq] },
+        backend,
+        input: { message: 'go' },
+      }),
+    )
+    expect(
+      events.filter((event) => event.type === 'text_delta').map((event) => event.text),
+    ).toEqual(['flat-wins'])
+  })
+
   it('parses OpenAI-compatible streamed chat completions', async () => {
     const backend = createOpenAICompatibleBackend({
       apiKey: 'sk-test',