fix(bb-agent): widen UseChatOptions.api sendMessage/resume return types to Promise<unknown>

[sharonyajain]

Problem

useChat's UseChatOptions.api types sendMessage and resume as Promise<void>, but the natural backend methods return objects — agent.stream() resolves to { channelId } and the resume wrappers to { ok: true }. Promise<{ channelId }> is not assignable to Promise<void> (TS2322: '{ channelId: string; }' is not assignable to 'void'), so a customer with a natural backend is forced into an await-and-discard wrapper:

// forced today:
sendMessage: async (convId, msg, chId) => { await api.sendMessage(convId, msg, chId); },
// wanted:
sendMessage: (convId, msg, chId) => api.sendMessage(convId, msg, chId),

useChat awaits both calls purely for completion and discards the resolved value (index.hooks.ts — await options.api.sendMessage(...) and await options.api.resume(...)), so the strict Promise<void> is unnecessarily narrow and buys nothing.

The README backend example currently dodges this by having sendMessage return void (it awaits agent.stream() without returning { channelId }) — the very workaround this change removes. The comprehensive test-app's agentStream returns { channelId } and agentResume returns { ok: true }, the natural shapes that hit the friction.

Issue #, if available:
no linked issue: reported via bug bash, no issue was filed.

Changes

• packages/bb-agent/src/index.hooks.ts: widen UseChatOptions.api.sendMessage and resume? return types from Promise<void> to Promise<unknown>. unknown is assignable-from both { ... } results and void, and since the hook discards the value this only widens what callers may return — no runtime behavior change, and existing void-returning backends keep compiling (backward compatible).
• packages/bb-agent/README.md: simplify the backend sendMessage example to return { channelId }, showing the natural, more useful shape now that the clean frontend wiring compiles.

The public ChatInstance.sendMessage / respondToInterrupt stay Promise<void> — those genuinely surface no value to the UI consumer. The change is scoped to the boundary where customer backends plug in.

Validation

• Verified the original friction reproduces the exact TS2322 (Promise<{ channelId: string; }> not assignable to Promise<void>) and that Promise<unknown> accepts both a natural { channelId } / { ok } backend and an existing void backend, confirming the fix works and is backward compatible.
• Typechecked the edited index.hooks.ts in isolation (it only imports ./types.js) — clean.
• No API report drift: API.md is generated by API Extractor from dist/index.aws.d.ts (the CDK/server entry point); UseChatOptions lives in the client entry point index.hooks.ts and does not appear in API.md, so no regeneration is needed.

Manual verification

N/A — type-only change plus a doc example; unit-level type assertions cover the behavior.

Checklist

• PR description included
• Tests are changed or added — N/A, this is a type-signature widening; no runtime code path changes and no new test hook exists for the client entry-point type surface
• Relevant documentation is changed or added (README backend example updated)

[changeset-bot]

🦋 Changeset detected

Latest commit: 12d197c

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
@aws-blocks/bb-agent	Patch
@aws-blocks/blocks	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR