@stackable-labs/mcp-app-extension 1.28.0 → 1.30.0

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { IDENTITY_EVENT, ACTIVITY_EVENT, SURFACE_TARGET, TEMPLATE_FLAVORS, PERMISSIONS, CAPABILITY_PERMISSION_MAP, EVENT_HOOK_PERMISSION_MAP, ALLOWED_ICONS, UI_TAGS, UI_TAG_CATEGORIES, UI_TAG_ATTRIBUTES, tagToComponentName } from '@stackable-labs/sdk-extension-contracts';
+import { IDENTITY_EVENT, ACTIVITY_EVENT, SURFACE_TARGET, TEMPLATE_FLAVORS, MESSAGING_ACTION_EXAMPLES, PERMISSIONS, CAPABILITY_PERMISSION_MAP, EVENT_HOOK_PERMISSION_MAP, ALLOWED_ICONS, UI_TAGS, UI_TAG_CATEGORIES, UI_TAG_ATTRIBUTES, tagToComponentName, MESSAGING_SEND_EXAMPLES } from '@stackable-labs/sdk-extension-contracts';
 import { validatePatternFormat } from '@stackable-labs/lib-contracts';
 import fs4, { readFile, mkdir, writeFile, constants } from 'fs/promises';
 import path, { join } from 'path';
@@ -541,7 +541,7 @@ var generateCapabilities = () => {
   const fm = frontmatter({
     root: false,
     targets: ["*"],
-    description: "Extension capabilities: data.query, data.fetch, context.read, actions.toast, actions.invoke, identity.extend, events:identity, events:messaging, events:activity",
+    description: "Extension capabilities: data.query, data.fetch, context.read, actions.toast, actions.invoke, identity.extend, messaging.send, events:identity, events:messaging, events:activity",
     globs: ["packages/extension/src/**/*.tsx", "packages/extension/src/**/*.ts"]
   });
   return `${fm}
@@ -798,7 +798,7 @@ await capabilities.identity.extend({
 // \u2192 identity:refresh broadcast to all extensions with events:identity
 \`\`\`
 
-Per-extension calls are serialized to prevent concurrent Zendesk \`loginUser\` callbacks from orphaning each other (empirically verified in the loginUser re-auth spike).
+Per-extension calls are serialized to prevent concurrent \`loginUser\` callbacks from orphaning each other.
 
 ### Consuming enriched state from another extension
 
@@ -831,6 +831,123 @@ The publisher-side bundle scan validates your declaration at submission time:
 | \`identityClaims_reserved_key\` | error | Collides with a reserved JWT / Zendesk claim |
 | \`identityClaims_standard_key\` | warning | Redundant \u2014 standard claims (\`external_id\`, \`email\`, \`name\`) are exempt |
 | \`identityClaims_too_many\` | error | More than 20 entries |
+
+## messaging.send \u2014 Send Messages to Conversations
+
+Post a message into the **active conversation** bound to the current Instance. The host attributes each message to the extension via the per-Instance author label set by the admin (see "Author label" below). Two complementary APIs:
+
+1. **\`useMessaging()\`** \u2014 React hook returning tuple \`[send, { loading, error, data }]\` \u2014 lets callers rename \`send\` per-instance when used multiple times in one component. Preferred for UI components; narrows the error surface to actionable codes only.
+2. **\`messagingSendCapability(payload)\`** / **\`capabilities.messaging.send(payload)\`** \u2014 imperative; useful outside React render. Exposes the full wire-level error taxonomy.
+
+### Manifest contract
+
+\`\`\`json
+{
+  "permissions": ["messaging:send"]
+}
+\`\`\`
+
+- **\`messaging:send\` permission** \u2014 without it the host gate rejects the call before any network request.
+
+### Author label (host-resolved, per-Instance)
+
+Extensions do **not** set the author label. The host resolves it from:
+1. \`instance.config.settings.messagingDisplayName\` \u2014 admin sets via the dashboard Instance form (visible only after OAuth completes; gated on \`messagingAppId\` being populated)
+2. **Fallback**: \`extension.manifest.name\` \u2014 used when admin hasn't set a label
+
+This prevents impersonation (extension A can't author as extension B) and gives admins per-deployment branding control.
+
+### Runtime requirements
+
+1. **Instance connected to a messaging provider** \u2014 bearer token stored, ready to post
+2. **An active conversation** when \`send()\` is called (else host-handled \`no_conversation\` \u2014 \`send()\` returns \`null\`)
+3. **Instance not disconnected** from the messaging provider (else host-handled \`reauth_required\` \u2014 admin reconnect surfaced in dashboard)
+
+### Payload \u2014 discriminated by \`kind\`
+
+Four kinds:
+
+| kind | Required fields | Optional |
+|---|---|---|
+| \`'text'\` | \`body: string\` | \`actions?: MessageItemAction[]\`, \`metadata?\`, \`htmlText?\`, \`markdownText?\`, \`disableUserInput?\` |
+| \`'image'\` | \`url: string\`, \`altText: string\` | \`body?\`, \`actions?\`, \`metadata?\` |
+| \`'file'\` | \`url: string\`, \`altText: string\` | \`body?\`, \`metadata?\` (no \`actions\` \u2014 file kind doesn't accept item-level actions) |
+| \`'carousel'\` | \`items: [MessageItem, ...MessageItem[]]\` (1\u201310 items, each with \`title\`, \`description?\`, \`imageUrl?\`, \`actions?\`) | \`displaySettings?: { imageAspectRatio?: 'square' \\| 'horizontal' }\` |
+
+**Action types** (per-item or per-message): \`reply\` (quick-reply button \u2014 emits postback to \`useMessagingEvent\`), \`link\` (opens URL), \`postback\` (custom payload to your handler), \`locationRequest\` (asks user for location).
+
+### Hook usage
+
+\`\`\`tsx
+import { useMessaging, useContextData } from '@stackable-labs/sdk-extension-react'
+
+const { messaging } = useContextData()
+const [send, { loading, error }] = useMessaging()
+
+// Proactive gate: skip the call when there's no conversation \u2014 avoids the
+// host-handled no_conversation log + null return.
+const canSend = !!messaging?.conversationId
+
+const onApprove = async () => {
+  try {
+    await send({
+      kind: 'text',
+      body: 'Order approved \u2713',
+      actions: [{ type: 'reply', label: 'Got it', payload: 'ACK' }],
+    })
+  } catch {
+    // error holds the typed SendMessageActionableErrorCode
+  }
+}
+
+if (error === 'rate_limited') {
+  // Render a "slow down" notice
+}
+\`\`\`
+
+### Imperative usage
+
+\`\`\`tsx
+const capabilities = useCapabilities()
+const result = await capabilities.messaging.send({ kind: 'text', body: 'Hello' })
+// result is either { messageId, receivedAt } OR { error: SendMessageErrorCode }
+\`\`\`
+
+### Typed error codes \u2014 split by who acts
+
+The wire taxonomy has 6 codes. The hook (\`useMessaging\`) narrows them into two groups:
+
+**Actionable (extension catches + renders UI)** \u2014 \`send()\` throws and \`state.error\` is populated:
+
+| Code | When |
+| --- | --- |
+| \`invalid_message\` | Payload failed validation (e.g. empty \`body\` for text, carousel >10 items, list kind sent) |
+| \`rate_limited\` | Upstream rate limit hit \u2014 back off + retry |
+| \`upstream_error\` | Provider returned 5xx \u2014 transient; retry with backoff |
+
+**Host-handled (extension ignores)** \u2014 \`send()\` resolves to \`null\`, \`state.error\` stays \`null\`, SDK logs a breadcrumb:
+
+| Code | What the framework does |
+| --- | --- |
+| \`no_conversation\` | \`console.info\` \u2014 pre-empt via \`useContextData().messaging?.conversationId\` |
+| \`reauth_required\` | \`console.warn\` \u2014 admin sees a "Reconnect" CTA in the dashboard (server flips \`messagingDisconnected: true\`) |
+| \`forbidden\` | \`console.warn\` \u2014 should not reach in production with correct manifest |
+
+The imperative \`messagingSendCapability\` path returns the full taxonomy without the actionable/host-handled split \u2014 useful when you need every code (e.g. dynamic dispatch).
+
+### Defense-in-depth gates
+
+Three gates fire in series, surfacing the same \`forbidden\` error if any blocks:
+
+1. **Embeddable host gate** (\`CapabilityRPCHandler\`) \u2014 checks \`sandbox.manifest.permissions.includes('messaging:send')\` before the call leaves the sandbox.
+2. **Backend handler gate** \u2014 checks \`claims.permissions?.includes('messaging:send')\` on the proxy-token JWT.
+3. **Server-side instance check** \u2014 \`instance.config.messagingDisconnected\` short-circuits with \`reauth_required\` before any upstream call.
+
+### Receiving replies \u2014 pair with \`events:messaging\`
+
+\`reply\` and \`postback\` action clicks fire on extensions with the \`events:messaging\` permission via \`useMessagingEvent\` \u2014 see the \`events:messaging\` section above.
+
+> **Note:** the postback \`payload\` field is currently not surfaced by the Web Widget (only the button text \`actionName\`). Until that gap is closed, design action labels to be self-describing or pair sends with a follow-up \`data.query\` lookup.
 `;
 };
 
@@ -1192,6 +1309,43 @@ export function Content(): React.ReactElement {
       <ui.Text className="text-xs">{lastEvent ?? 'No activity yet'}</ui.Text>
     </Surface>
   )
+}`,
+  "messaging.send": `import { useMessaging, useContextData, Surface, ui } from '@stackable-labs/sdk-extension-react'
+
+// Requires 'messaging:send' permission. send() throws on actionable errors
+// (state.error holds the typed code); resolves to null on host-handled cases.
+export function Content(): React.ReactElement {
+  const { messaging } = useContextData()
+  const [send, { loading, error }] = useMessaging()
+  // Proactive gate: skip the call when there's no conversation \u2014 avoids the
+  // host-handled no_conversation log + null return.
+  const canSend = !!messaging?.conversationId
+
+  const onSayHello = async () => {
+    try {
+      await send({
+        kind: 'text',
+        body: 'Hello from the extension',
+        actions: [
+          { type: 'reply', label: 'Sounds good', payload: 'ACK' },
+          { type: 'reply', label: 'Maybe later', payload: 'DEFER' },
+        ],
+      })
+    } catch {
+      // error holds the typed SendMessageActionableErrorCode
+    }
+  }
+
+  return (
+    <Surface id="slot.content">
+      <ui.Stack direction="column" gap="2" className="p-3">
+        <ui.Button onClick={onSayHello} disabled={loading || !canSend}>Say hello</ui.Button>
+        {(error === 'rate_limited') && <ui.Alert variant="warning">Slow down \u2014 sent too many.</ui.Alert>}
+        {(error === 'upstream_error') && <ui.Alert variant="error">Send failed \u2014 please try again.</ui.Alert>}
+        {(error === 'invalid_message') && <ui.Alert variant="error">Send failed \u2014 message format invalid.</ui.Alert>}
+      </ui.Stack>
+    </Surface>
+  )
 }`
 };
 
@@ -1235,6 +1389,7 @@ const capabilities = useCapabilities()
 // capabilities.actions.toast(payload)
 // capabilities.actions.invoke(action, payload?) \u2014 actions: newConversation, setConversationTags, setConversationFields, open, close, show, hide
 // capabilities.identity.extend(patch) \u2014 push enrichment claims to user.metadata + JWT custom_claims (imperative; for handler-style at login, use useExtendIdentity hook). Each patch key MUST be declared in manifest.identityClaims or the host filter drops it.
+// capabilities.messaging.send(payload) \u2014 post a message into the active conversation bound to this Instance. Requires messaging:send permission. Author label is admin-set per-Instance (instance.config.settings.messagingDisplayName) with extension.manifest.name fallback. For React state ([send, { loading, error, data }]), prefer the useMessaging hook.
 \`\`\`
 
 ## useStore(store, selector?)
@@ -1351,6 +1506,35 @@ Identity state is available in the \`context.read()\` response as an \`identity\
 const context = await capabilities.context.read()
 // context.identity \u2014 { authenticated, user, expiresAt? }
 \`\`\`
+
+## useMessaging()
+Send messages into the active conversation bound to this Instance. Wraps the \`messaging.send\` capability with React state, tracking \`loading\` / \`error\` / \`data\`. Returns a tuple \`[send, state]\` so callers can rename \`send\` when the hook is used multiple times in one component. Requires \`messaging:send\` permission. The author label rendered above outbound messages is set per-Instance by the admin (Instance settings \`messagingDisplayName\`); falls back to \`extension.manifest.name\` when blank.
+
+- **Returns:** \`readonly [send, { loading, error, data }]\`
+- **\`send(payload: SendMessagePayload): Promise<SendMessageResponse | null>\`** \u2014 returns the response on success; throws on **actionable** errors; resolves to \`null\` on host-handled errors (SDK logs a breadcrumb, host surfaces remediation)
+- **\`loading: boolean\`** \u2014 true while a call is in flight (matches \`useContextData\`'s \`loading\` for SDK-wide consistency)
+- **\`data: SendMessageResponse | null\`** \u2014 \`{ messageId, receivedAt }\` from last successful send
+- **\`error: SendMessageActionableErrorCode | null\`** \u2014 one of \`invalid_message\` / \`rate_limited\` / \`upstream_error\` after a failed send. Host-handled codes (\`no_conversation\` / \`reauth_required\` / \`forbidden\`) never surface here.
+
+Payload is discriminated by \`kind\`: \`'text'\` / \`'image'\` / \`'file'\` / \`'carousel'\`. See the \`messaging.send\` capability section for the full payload table + action types.
+
+\`\`\`tsx
+import { useMessaging, useContextData } from '@stackable-labs/sdk-extension-react'
+
+const { messaging } = useContextData()
+const [send, { loading, error }] = useMessaging()
+
+// Proactive gate: skip the call when there's no conversation
+const canSend = !!messaging?.conversationId
+
+const onApprove = async () => {
+  try {
+    await send({ kind: 'text', body: 'Approved \u2713' })
+  } catch {
+    // error holds the typed SendMessageActionableErrorCode
+  }
+}
+\`\`\`
 `;
 };
 
@@ -3612,6 +3796,27 @@ updating custom fields.
 \`\`\`tsx
 ${EXAMPLE_SNIPPETS["actions.invoke"]}
 \`\`\`
+
+## messaging.send \u2014 Sending Messages to Conversations
+
+Post a message into the active conversation bound to this Instance via the
+\`useMessaging\` React hook. Returns the response on happy path and throws on
+**actionable** errors \u2014 inspect \`error\` for one of the typed
+\`SendMessageActionableErrorCode\` values (\`invalid_message\`, \`rate_limited\`,
+\`upstream_error\`). Host-handled cases (\`no_conversation\`, \`reauth_required\`,
+\`forbidden\`) resolve to \`null\` without throwing; the SDK logs a breadcrumb
+and the host surfaces remediation to admins (e.g. dashboard reconnect UI) \u2014
+extensions don't catch them.
+
+**Permission:** \`messaging:send\`. The author label rendered above outbound
+messages is set **per-Instance by the admin** via the Instance settings field
+\`messagingDisplayName\` (visible on the dashboard once OAuth completes);
+falls back to \`extension.manifest.name\` when blank. Extensions do not set or
+think about the author identity.
+
+\`\`\`tsx
+${EXAMPLE_SNIPPETS["messaging.send"]}
+\`\`\`
 `;
 };
 var generateCookbookStructural = () => {
@@ -3695,6 +3900,108 @@ ${EXAMPLE_SNIPPETS.surfaceContext}
 \`\`\`
 `;
 };
+var renderPayload = (kind) => JSON.stringify(MESSAGING_SEND_EXAMPLES[kind], null, 2);
+var renderAction = (type) => JSON.stringify(MESSAGING_ACTION_EXAMPLES[type], null, 2);
+var ACTION_DESCRIPTIONS = {
+  reply: "Inserts a visible user-reply bubble carrying `payload` back into the conversation, as if the user typed it. **Mutually exclusive** \u2014 a `reply` action cannot share an `actions[]` array with any other action type; the host validates and surfaces `invalid_message` if mixed.",
+  link: "Opens `url` in a new tab/window. No bubble inserted. Freely mixable with other non-reply actions.",
+  postback: "Fires a server-side `conversation:postback` webhook to the Stackable backend carrying the full `payload` + any `metadata`. NO visible bubble. Extensions with the `events:messaging` permission receive postback events via `useMessagingEvent` \u2014 see the **Events & Identity** cookbook.",
+  locationRequest: "Prompts the user to share device location. Response arrives as a separate `location`-type message inbound to the conversation. Freely mixable."
+};
+var actionTypeSections = Object.keys(MESSAGING_ACTION_EXAMPLES).map((type) => `### type: '${type}'
+
+${ACTION_DESCRIPTIONS[type]}
+
+\`\`\`tsx
+${renderAction(type)}
+\`\`\``).join("\n\n");
+var generateCookbookMessaging = () => {
+  const fm = frontmatter({
+    root: false,
+    targets: ["*"],
+    description: "Cookbook: example payloads per-kind for the messaging.send capability + action type shapes",
+    globs: ["packages/extension/src/**/*.tsx", "packages/extension/src/**/*.ts"]
+  });
+  return `${fm}
+
+# Messaging Examples
+
+Example payloads for the \`messaging.send\` capability \u2014 one per supported message
+kind, plus the action types you can attach to messages. Each payload is the
+exact shape the \`useMessaging\` hook accepts; copy and adapt as needed.
+
+**Permission:** \`messaging:send\` in your \`manifest.json\`. The author label
+above outbound messages is set **per-Instance by the admin** via the Instance
+settings field \`messagingDisplayName\`; falls back to \`extension.manifest.name\`
+when blank. Extensions do not set or think about the author identity.
+
+---
+
+## kind: 'text' \u2014 Plain text + reply actions
+
+Plain conversational message. Optional \`actions\` array attaches quick-reply
+buttons, links, postbacks, or location requests.
+
+\`\`\`tsx
+const [send] = useMessaging()
+
+await send(${renderPayload("text")})
+\`\`\`
+
+## kind: 'image' \u2014 Embedded image + optional caption
+
+Product photos, screenshots, visual help. \`url\` must respond with a
+\`Content-Type: image/*\` header (Sunco enforces; redirecting URLs like
+\`picsum.photos\` will fail). \`altText\` is optional \u2014 defaults to filename.
+Optional \`body\` renders a caption alongside the image.
+
+\`\`\`tsx
+const [send] = useMessaging()
+
+await send(${renderPayload("image")})
+\`\`\`
+
+## kind: 'file' \u2014 Embedded file attachment
+
+Return labels, receipts, NDAs, warranty paperwork. Sunco's \`fileMessage\`
+schema does NOT support \`actions\` \u2014 file messages can only carry an
+optional text caption.
+
+\`\`\`tsx
+const [send] = useMessaging()
+
+await send(${renderPayload("file")})
+\`\`\`
+
+## kind: 'carousel' \u2014 Horizontally scrolling cards
+
+The conversational-commerce primitive: product recommendations, size/color
+pickers, search results with images, multi-option selection.
+
+- 1\u201310 items, each with required \`title\` + required \`actions\` (1\u20133 per item)
+- Item actions are a subset: \`link\` + \`postback\` only (no \`reply\`, no
+  \`locationRequest\` \u2014 Sunco rejects those at the item level)
+- Carousel messages have NO message-level \`actions\` field \u2014 actions live
+  per-card
+- Use a separate \`text\` message before the carousel if you need an intro
+
+\`\`\`tsx
+const [send] = useMessaging()
+
+await send(${renderPayload("carousel")})
+\`\`\`
+
+---
+
+## Action types
+
+Attach to message-level \`actions\` (text / image) or item-level \`actions\`
+(carousel). All actions share \`label\` + optional \`metadata\` (primitives only,
+\u22644KB total).
+
+${actionTypeSections}
+`;
+};
 var identityEventTypes2 = Object.values(IDENTITY_EVENT).map((e) => `\`${e}\``).join(", ");
 var activityEventTypes2 = Object.values(ACTIVITY_EVENT).map((e) => `\`${e}\``).join(", ");
 var generateCookbookEvents = () => {
@@ -3716,7 +4023,7 @@ supports both a login-time hook (\`useExtendIdentity\`) and an imperative post-l
 
 ## Messaging Events
 
-Subscribe to postback button clicks from the Zendesk messaging widget.
+Subscribe to postback button clicks from the Messaging widget.
 The \`actionName\` is the button's display text, not a programmatic identifier.
 
 **Permission:** \`events:messaging\`
@@ -3929,6 +4236,23 @@ await capabilities.identity.extend({ verified: true })
 useIdentityEvent('refresh', (event) => {
   console.log('verified =>', event.data.state.user?.metadata?.verified)
 })
+`,
+  "messaging.send": `
+// Send a message into the active conversation bound to this Instance.
+// Requires the 'messaging:send' permission. The author label rendered above
+// outbound messages is set per-Instance by the admin (Instance settings
+// messagingDisplayName); falls back to extension.manifest.name when blank.
+const [send, { loading, error }] = useMessaging()
+const result = await send({ kind: 'text', body: 'Hello from the extension' })
+
+// Actionable errors throw + populate state.error: 'invalid_message' (bad payload),
+// 'rate_limited' (slow down), 'upstream_error' (transient \u2014 retry). Branch in
+// catch / on state.error to show UX.
+// Host-handled cases ('no_conversation' / 'reauth_required' / 'forbidden')
+// resolve to null without throwing; the SDK logs a breadcrumb and the host
+// surfaces remediation to admins (e.g. dashboard Reconnect UI). Extensions
+// can pre-empt 'no_conversation' via useContextData().messaging?.conversationId.
+if (error === 'rate_limited') { /* show "slow down" UI */ }
 `
 };
 var EVENT_SNIPPETS = {
@@ -4582,6 +4906,13 @@ var SKILLS = [
     scopes: ["docs"],
     content: () => generateCookbookEvents()
   },
+  {
+    id: "cookbook-messaging",
+    description: "Cookbook: per-kind example payloads (text / image / file / carousel) and action types (reply / link / postback / locationRequest) for the messaging.send capability. Use when wiring the useMessaging hook or composing outbound conversation messages.",
+    type: "knowledge",
+    scopes: ["docs"],
+    content: () => generateCookbookMessaging()
+  },
   {
     id: "marketplace-listing",
     description: "Marketplace listing reference: the listing fields (icon, screenshots, description, categories), Public vs Protected visibility, and the two-stage review process (bundle scan + security review + approval). Use when publishing a deployed extension to the marketplace.",
@@ -5051,6 +5382,43 @@ export function Content() {
       <ui.Text className="text-xs">{lastEvent ?? 'No activity yet'}</ui.Text>
     </Surface>
   )
+}`,
+  "messaging.send": `import { useMessaging, useContextData, Surface, ui } from '@stackable-labs/sdk-extension-react'
+
+// Requires 'messaging:send' permission. send() throws on actionable errors
+// (state.error holds the typed code); resolves to null on host-handled cases.
+export function Content() {
+  const { messaging } = useContextData()
+  const [send, { loading, error }] = useMessaging()
+  // Proactive gate: skip the call when there's no conversation \u2014 avoids the
+  // host-handled no_conversation log + null return.
+  const canSend = !!messaging?.conversationId
+
+  const onSayHello = async () => {
+    try {
+      await send({
+        kind: 'text',
+        body: 'Hello from the extension',
+        actions: [
+          { type: 'reply', label: 'Sounds good', payload: 'ACK' },
+          { type: 'reply', label: 'Maybe later', payload: 'DEFER' },
+        ],
+      })
+    } catch {
+      // error holds the typed SendMessageActionableErrorCode
+    }
+  }
+
+  return (
+    <Surface id="slot.content">
+      <ui.Stack direction="column" gap="2" className="p-3">
+        <ui.Button onClick={onSayHello} disabled={loading || !canSend}>Say hello</ui.Button>
+        {(error === 'rate_limited') && <ui.Alert variant="warning">Slow down \u2014 sent too many.</ui.Alert>}
+        {(error === 'upstream_error') && <ui.Alert variant="error">Send failed \u2014 please try again.</ui.Alert>}
+        {(error === 'invalid_message') && <ui.Alert variant="error">Send failed \u2014 message format invalid.</ui.Alert>}
+      </ui.Stack>
+    </Surface>
+  )
 }`
 };
 
@@ -5142,7 +5510,22 @@ await capabilities.identity.extend({ verified: true })
 // Consumer side \u2014 same or sibling extension reacts via identity:refresh
 useIdentityEvent('refresh', (event) => {
   console.log('verified =>', event.data.state.user?.metadata?.verified)
-})`
+})`,
+  "messaging.send": `// Send a message into the active conversation bound to this Instance.
+// Requires the 'messaging:send' permission. The author label rendered above
+// outbound messages is set per-Instance by the admin (Instance settings
+// messagingDisplayName); falls back to extension.manifest.name when blank.
+const [send, { loading, error }] = useMessaging()
+const result = await send({ kind: 'text', body: 'Hello from the extension' })
+
+// Actionable errors throw + populate state.error: 'invalid_message' (bad payload),
+// 'rate_limited' (slow down), 'upstream_error' (transient \u2014 retry). Branch in
+// catch / on state.error to show UX.
+// Host-handled cases ('no_conversation' / 'reauth_required' / 'forbidden')
+// resolve to null without throwing; the SDK logs a breadcrumb and the host
+// surfaces remediation to admins (e.g. dashboard Reconnect UI). Extensions
+// can pre-empt 'no_conversation' via useContextData().messaging?.conversationId.
+if (error === 'rate_limited') { /* show "slow down" UI */ }`
 };
 var EVENT_SNIPPETS2 = {
   "events:identity": `import { useIdentityEvent, Surface, ui } from '@stackable-labs/sdk-extension-react'

package/dist/server.js

@@ -1,5 +1,5 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { IDENTITY_EVENT, ACTIVITY_EVENT, SURFACE_TARGET, TEMPLATE_FLAVORS, PERMISSIONS, CAPABILITY_PERMISSION_MAP, EVENT_HOOK_PERMISSION_MAP, ALLOWED_ICONS, UI_TAGS, UI_TAG_CATEGORIES, UI_TAG_ATTRIBUTES, tagToComponentName } from '@stackable-labs/sdk-extension-contracts';
+import { IDENTITY_EVENT, ACTIVITY_EVENT, SURFACE_TARGET, TEMPLATE_FLAVORS, MESSAGING_ACTION_EXAMPLES, PERMISSIONS, CAPABILITY_PERMISSION_MAP, EVENT_HOOK_PERMISSION_MAP, ALLOWED_ICONS, UI_TAGS, UI_TAG_CATEGORIES, UI_TAG_ATTRIBUTES, tagToComponentName, MESSAGING_SEND_EXAMPLES } from '@stackable-labs/sdk-extension-contracts';
 import { validatePatternFormat } from '@stackable-labs/lib-contracts';
 import { readFile } from 'fs/promises';
 import { join } from 'path';
@@ -534,7 +534,7 @@ var generateCapabilities = () => {
   const fm = frontmatter({
     root: false,
     targets: ["*"],
-    description: "Extension capabilities: data.query, data.fetch, context.read, actions.toast, actions.invoke, identity.extend, events:identity, events:messaging, events:activity",
+    description: "Extension capabilities: data.query, data.fetch, context.read, actions.toast, actions.invoke, identity.extend, messaging.send, events:identity, events:messaging, events:activity",
     globs: ["packages/extension/src/**/*.tsx", "packages/extension/src/**/*.ts"]
   });
   return `${fm}
@@ -791,7 +791,7 @@ await capabilities.identity.extend({
 // \u2192 identity:refresh broadcast to all extensions with events:identity
 \`\`\`
 
-Per-extension calls are serialized to prevent concurrent Zendesk \`loginUser\` callbacks from orphaning each other (empirically verified in the loginUser re-auth spike).
+Per-extension calls are serialized to prevent concurrent \`loginUser\` callbacks from orphaning each other.
 
 ### Consuming enriched state from another extension
 
@@ -824,6 +824,123 @@ The publisher-side bundle scan validates your declaration at submission time:
 | \`identityClaims_reserved_key\` | error | Collides with a reserved JWT / Zendesk claim |
 | \`identityClaims_standard_key\` | warning | Redundant \u2014 standard claims (\`external_id\`, \`email\`, \`name\`) are exempt |
 | \`identityClaims_too_many\` | error | More than 20 entries |
+
+## messaging.send \u2014 Send Messages to Conversations
+
+Post a message into the **active conversation** bound to the current Instance. The host attributes each message to the extension via the per-Instance author label set by the admin (see "Author label" below). Two complementary APIs:
+
+1. **\`useMessaging()\`** \u2014 React hook returning tuple \`[send, { loading, error, data }]\` \u2014 lets callers rename \`send\` per-instance when used multiple times in one component. Preferred for UI components; narrows the error surface to actionable codes only.
+2. **\`messagingSendCapability(payload)\`** / **\`capabilities.messaging.send(payload)\`** \u2014 imperative; useful outside React render. Exposes the full wire-level error taxonomy.
+
+### Manifest contract
+
+\`\`\`json
+{
+  "permissions": ["messaging:send"]
+}
+\`\`\`
+
+- **\`messaging:send\` permission** \u2014 without it the host gate rejects the call before any network request.
+
+### Author label (host-resolved, per-Instance)
+
+Extensions do **not** set the author label. The host resolves it from:
+1. \`instance.config.settings.messagingDisplayName\` \u2014 admin sets via the dashboard Instance form (visible only after OAuth completes; gated on \`messagingAppId\` being populated)
+2. **Fallback**: \`extension.manifest.name\` \u2014 used when admin hasn't set a label
+
+This prevents impersonation (extension A can't author as extension B) and gives admins per-deployment branding control.
+
+### Runtime requirements
+
+1. **Instance connected to a messaging provider** \u2014 bearer token stored, ready to post
+2. **An active conversation** when \`send()\` is called (else host-handled \`no_conversation\` \u2014 \`send()\` returns \`null\`)
+3. **Instance not disconnected** from the messaging provider (else host-handled \`reauth_required\` \u2014 admin reconnect surfaced in dashboard)
+
+### Payload \u2014 discriminated by \`kind\`
+
+Four kinds:
+
+| kind | Required fields | Optional |
+|---|---|---|
+| \`'text'\` | \`body: string\` | \`actions?: MessageItemAction[]\`, \`metadata?\`, \`htmlText?\`, \`markdownText?\`, \`disableUserInput?\` |
+| \`'image'\` | \`url: string\`, \`altText: string\` | \`body?\`, \`actions?\`, \`metadata?\` |
+| \`'file'\` | \`url: string\`, \`altText: string\` | \`body?\`, \`metadata?\` (no \`actions\` \u2014 file kind doesn't accept item-level actions) |
+| \`'carousel'\` | \`items: [MessageItem, ...MessageItem[]]\` (1\u201310 items, each with \`title\`, \`description?\`, \`imageUrl?\`, \`actions?\`) | \`displaySettings?: { imageAspectRatio?: 'square' \\| 'horizontal' }\` |
+
+**Action types** (per-item or per-message): \`reply\` (quick-reply button \u2014 emits postback to \`useMessagingEvent\`), \`link\` (opens URL), \`postback\` (custom payload to your handler), \`locationRequest\` (asks user for location).
+
+### Hook usage
+
+\`\`\`tsx
+import { useMessaging, useContextData } from '@stackable-labs/sdk-extension-react'
+
+const { messaging } = useContextData()
+const [send, { loading, error }] = useMessaging()
+
+// Proactive gate: skip the call when there's no conversation \u2014 avoids the
+// host-handled no_conversation log + null return.
+const canSend = !!messaging?.conversationId
+
+const onApprove = async () => {
+  try {
+    await send({
+      kind: 'text',
+      body: 'Order approved \u2713',
+      actions: [{ type: 'reply', label: 'Got it', payload: 'ACK' }],
+    })
+  } catch {
+    // error holds the typed SendMessageActionableErrorCode
+  }
+}
+
+if (error === 'rate_limited') {
+  // Render a "slow down" notice
+}
+\`\`\`
+
+### Imperative usage
+
+\`\`\`tsx
+const capabilities = useCapabilities()
+const result = await capabilities.messaging.send({ kind: 'text', body: 'Hello' })
+// result is either { messageId, receivedAt } OR { error: SendMessageErrorCode }
+\`\`\`
+
+### Typed error codes \u2014 split by who acts
+
+The wire taxonomy has 6 codes. The hook (\`useMessaging\`) narrows them into two groups:
+
+**Actionable (extension catches + renders UI)** \u2014 \`send()\` throws and \`state.error\` is populated:
+
+| Code | When |
+| --- | --- |
+| \`invalid_message\` | Payload failed validation (e.g. empty \`body\` for text, carousel >10 items, list kind sent) |
+| \`rate_limited\` | Upstream rate limit hit \u2014 back off + retry |
+| \`upstream_error\` | Provider returned 5xx \u2014 transient; retry with backoff |
+
+**Host-handled (extension ignores)** \u2014 \`send()\` resolves to \`null\`, \`state.error\` stays \`null\`, SDK logs a breadcrumb:
+
+| Code | What the framework does |
+| --- | --- |
+| \`no_conversation\` | \`console.info\` \u2014 pre-empt via \`useContextData().messaging?.conversationId\` |
+| \`reauth_required\` | \`console.warn\` \u2014 admin sees a "Reconnect" CTA in the dashboard (server flips \`messagingDisconnected: true\`) |
+| \`forbidden\` | \`console.warn\` \u2014 should not reach in production with correct manifest |
+
+The imperative \`messagingSendCapability\` path returns the full taxonomy without the actionable/host-handled split \u2014 useful when you need every code (e.g. dynamic dispatch).
+
+### Defense-in-depth gates
+
+Three gates fire in series, surfacing the same \`forbidden\` error if any blocks:
+
+1. **Embeddable host gate** (\`CapabilityRPCHandler\`) \u2014 checks \`sandbox.manifest.permissions.includes('messaging:send')\` before the call leaves the sandbox.
+2. **Backend handler gate** \u2014 checks \`claims.permissions?.includes('messaging:send')\` on the proxy-token JWT.
+3. **Server-side instance check** \u2014 \`instance.config.messagingDisconnected\` short-circuits with \`reauth_required\` before any upstream call.
+
+### Receiving replies \u2014 pair with \`events:messaging\`
+
+\`reply\` and \`postback\` action clicks fire on extensions with the \`events:messaging\` permission via \`useMessagingEvent\` \u2014 see the \`events:messaging\` section above.
+
+> **Note:** the postback \`payload\` field is currently not surfaced by the Web Widget (only the button text \`actionName\`). Until that gap is closed, design action labels to be self-describing or pair sends with a follow-up \`data.query\` lookup.
 `;
 };
 
@@ -1185,6 +1302,43 @@ export function Content(): React.ReactElement {
       <ui.Text className="text-xs">{lastEvent ?? 'No activity yet'}</ui.Text>
     </Surface>
   )
+}`,
+  "messaging.send": `import { useMessaging, useContextData, Surface, ui } from '@stackable-labs/sdk-extension-react'
+
+// Requires 'messaging:send' permission. send() throws on actionable errors
+// (state.error holds the typed code); resolves to null on host-handled cases.
+export function Content(): React.ReactElement {
+  const { messaging } = useContextData()
+  const [send, { loading, error }] = useMessaging()
+  // Proactive gate: skip the call when there's no conversation \u2014 avoids the
+  // host-handled no_conversation log + null return.
+  const canSend = !!messaging?.conversationId
+
+  const onSayHello = async () => {
+    try {
+      await send({
+        kind: 'text',
+        body: 'Hello from the extension',
+        actions: [
+          { type: 'reply', label: 'Sounds good', payload: 'ACK' },
+          { type: 'reply', label: 'Maybe later', payload: 'DEFER' },
+        ],
+      })
+    } catch {
+      // error holds the typed SendMessageActionableErrorCode
+    }
+  }
+
+  return (
+    <Surface id="slot.content">
+      <ui.Stack direction="column" gap="2" className="p-3">
+        <ui.Button onClick={onSayHello} disabled={loading || !canSend}>Say hello</ui.Button>
+        {(error === 'rate_limited') && <ui.Alert variant="warning">Slow down \u2014 sent too many.</ui.Alert>}
+        {(error === 'upstream_error') && <ui.Alert variant="error">Send failed \u2014 please try again.</ui.Alert>}
+        {(error === 'invalid_message') && <ui.Alert variant="error">Send failed \u2014 message format invalid.</ui.Alert>}
+      </ui.Stack>
+    </Surface>
+  )
 }`
 };
 
@@ -1228,6 +1382,7 @@ const capabilities = useCapabilities()
 // capabilities.actions.toast(payload)
 // capabilities.actions.invoke(action, payload?) \u2014 actions: newConversation, setConversationTags, setConversationFields, open, close, show, hide
 // capabilities.identity.extend(patch) \u2014 push enrichment claims to user.metadata + JWT custom_claims (imperative; for handler-style at login, use useExtendIdentity hook). Each patch key MUST be declared in manifest.identityClaims or the host filter drops it.
+// capabilities.messaging.send(payload) \u2014 post a message into the active conversation bound to this Instance. Requires messaging:send permission. Author label is admin-set per-Instance (instance.config.settings.messagingDisplayName) with extension.manifest.name fallback. For React state ([send, { loading, error, data }]), prefer the useMessaging hook.
 \`\`\`
 
 ## useStore(store, selector?)
@@ -1344,6 +1499,35 @@ Identity state is available in the \`context.read()\` response as an \`identity\
 const context = await capabilities.context.read()
 // context.identity \u2014 { authenticated, user, expiresAt? }
 \`\`\`
+
+## useMessaging()
+Send messages into the active conversation bound to this Instance. Wraps the \`messaging.send\` capability with React state, tracking \`loading\` / \`error\` / \`data\`. Returns a tuple \`[send, state]\` so callers can rename \`send\` when the hook is used multiple times in one component. Requires \`messaging:send\` permission. The author label rendered above outbound messages is set per-Instance by the admin (Instance settings \`messagingDisplayName\`); falls back to \`extension.manifest.name\` when blank.
+
+- **Returns:** \`readonly [send, { loading, error, data }]\`
+- **\`send(payload: SendMessagePayload): Promise<SendMessageResponse | null>\`** \u2014 returns the response on success; throws on **actionable** errors; resolves to \`null\` on host-handled errors (SDK logs a breadcrumb, host surfaces remediation)
+- **\`loading: boolean\`** \u2014 true while a call is in flight (matches \`useContextData\`'s \`loading\` for SDK-wide consistency)
+- **\`data: SendMessageResponse | null\`** \u2014 \`{ messageId, receivedAt }\` from last successful send
+- **\`error: SendMessageActionableErrorCode | null\`** \u2014 one of \`invalid_message\` / \`rate_limited\` / \`upstream_error\` after a failed send. Host-handled codes (\`no_conversation\` / \`reauth_required\` / \`forbidden\`) never surface here.
+
+Payload is discriminated by \`kind\`: \`'text'\` / \`'image'\` / \`'file'\` / \`'carousel'\`. See the \`messaging.send\` capability section for the full payload table + action types.
+
+\`\`\`tsx
+import { useMessaging, useContextData } from '@stackable-labs/sdk-extension-react'
+
+const { messaging } = useContextData()
+const [send, { loading, error }] = useMessaging()
+
+// Proactive gate: skip the call when there's no conversation
+const canSend = !!messaging?.conversationId
+
+const onApprove = async () => {
+  try {
+    await send({ kind: 'text', body: 'Approved \u2713' })
+  } catch {
+    // error holds the typed SendMessageActionableErrorCode
+  }
+}
+\`\`\`
 `;
 };
 
@@ -3605,6 +3789,27 @@ updating custom fields.
 \`\`\`tsx
 ${EXAMPLE_SNIPPETS["actions.invoke"]}
 \`\`\`
+
+## messaging.send \u2014 Sending Messages to Conversations
+
+Post a message into the active conversation bound to this Instance via the
+\`useMessaging\` React hook. Returns the response on happy path and throws on
+**actionable** errors \u2014 inspect \`error\` for one of the typed
+\`SendMessageActionableErrorCode\` values (\`invalid_message\`, \`rate_limited\`,
+\`upstream_error\`). Host-handled cases (\`no_conversation\`, \`reauth_required\`,
+\`forbidden\`) resolve to \`null\` without throwing; the SDK logs a breadcrumb
+and the host surfaces remediation to admins (e.g. dashboard reconnect UI) \u2014
+extensions don't catch them.
+
+**Permission:** \`messaging:send\`. The author label rendered above outbound
+messages is set **per-Instance by the admin** via the Instance settings field
+\`messagingDisplayName\` (visible on the dashboard once OAuth completes);
+falls back to \`extension.manifest.name\` when blank. Extensions do not set or
+think about the author identity.
+
+\`\`\`tsx
+${EXAMPLE_SNIPPETS["messaging.send"]}
+\`\`\`
 `;
 };
 var generateCookbookStructural = () => {
@@ -3688,6 +3893,108 @@ ${EXAMPLE_SNIPPETS.surfaceContext}
 \`\`\`
 `;
 };
+var renderPayload = (kind) => JSON.stringify(MESSAGING_SEND_EXAMPLES[kind], null, 2);
+var renderAction = (type) => JSON.stringify(MESSAGING_ACTION_EXAMPLES[type], null, 2);
+var ACTION_DESCRIPTIONS = {
+  reply: "Inserts a visible user-reply bubble carrying `payload` back into the conversation, as if the user typed it. **Mutually exclusive** \u2014 a `reply` action cannot share an `actions[]` array with any other action type; the host validates and surfaces `invalid_message` if mixed.",
+  link: "Opens `url` in a new tab/window. No bubble inserted. Freely mixable with other non-reply actions.",
+  postback: "Fires a server-side `conversation:postback` webhook to the Stackable backend carrying the full `payload` + any `metadata`. NO visible bubble. Extensions with the `events:messaging` permission receive postback events via `useMessagingEvent` \u2014 see the **Events & Identity** cookbook.",
+  locationRequest: "Prompts the user to share device location. Response arrives as a separate `location`-type message inbound to the conversation. Freely mixable."
+};
+var actionTypeSections = Object.keys(MESSAGING_ACTION_EXAMPLES).map((type) => `### type: '${type}'
+
+${ACTION_DESCRIPTIONS[type]}
+
+\`\`\`tsx
+${renderAction(type)}
+\`\`\``).join("\n\n");
+var generateCookbookMessaging = () => {
+  const fm = frontmatter({
+    root: false,
+    targets: ["*"],
+    description: "Cookbook: example payloads per-kind for the messaging.send capability + action type shapes",
+    globs: ["packages/extension/src/**/*.tsx", "packages/extension/src/**/*.ts"]
+  });
+  return `${fm}
+
+# Messaging Examples
+
+Example payloads for the \`messaging.send\` capability \u2014 one per supported message
+kind, plus the action types you can attach to messages. Each payload is the
+exact shape the \`useMessaging\` hook accepts; copy and adapt as needed.
+
+**Permission:** \`messaging:send\` in your \`manifest.json\`. The author label
+above outbound messages is set **per-Instance by the admin** via the Instance
+settings field \`messagingDisplayName\`; falls back to \`extension.manifest.name\`
+when blank. Extensions do not set or think about the author identity.
+
+---
+
+## kind: 'text' \u2014 Plain text + reply actions
+
+Plain conversational message. Optional \`actions\` array attaches quick-reply
+buttons, links, postbacks, or location requests.
+
+\`\`\`tsx
+const [send] = useMessaging()
+
+await send(${renderPayload("text")})
+\`\`\`
+
+## kind: 'image' \u2014 Embedded image + optional caption
+
+Product photos, screenshots, visual help. \`url\` must respond with a
+\`Content-Type: image/*\` header (Sunco enforces; redirecting URLs like
+\`picsum.photos\` will fail). \`altText\` is optional \u2014 defaults to filename.
+Optional \`body\` renders a caption alongside the image.
+
+\`\`\`tsx
+const [send] = useMessaging()
+
+await send(${renderPayload("image")})
+\`\`\`
+
+## kind: 'file' \u2014 Embedded file attachment
+
+Return labels, receipts, NDAs, warranty paperwork. Sunco's \`fileMessage\`
+schema does NOT support \`actions\` \u2014 file messages can only carry an
+optional text caption.
+
+\`\`\`tsx
+const [send] = useMessaging()
+
+await send(${renderPayload("file")})
+\`\`\`
+
+## kind: 'carousel' \u2014 Horizontally scrolling cards
+
+The conversational-commerce primitive: product recommendations, size/color
+pickers, search results with images, multi-option selection.
+
+- 1\u201310 items, each with required \`title\` + required \`actions\` (1\u20133 per item)
+- Item actions are a subset: \`link\` + \`postback\` only (no \`reply\`, no
+  \`locationRequest\` \u2014 Sunco rejects those at the item level)
+- Carousel messages have NO message-level \`actions\` field \u2014 actions live
+  per-card
+- Use a separate \`text\` message before the carousel if you need an intro
+
+\`\`\`tsx
+const [send] = useMessaging()
+
+await send(${renderPayload("carousel")})
+\`\`\`
+
+---
+
+## Action types
+
+Attach to message-level \`actions\` (text / image) or item-level \`actions\`
+(carousel). All actions share \`label\` + optional \`metadata\` (primitives only,
+\u22644KB total).
+
+${actionTypeSections}
+`;
+};
 var identityEventTypes2 = Object.values(IDENTITY_EVENT).map((e) => `\`${e}\``).join(", ");
 var activityEventTypes2 = Object.values(ACTIVITY_EVENT).map((e) => `\`${e}\``).join(", ");
 var generateCookbookEvents = () => {
@@ -3709,7 +4016,7 @@ supports both a login-time hook (\`useExtendIdentity\`) and an imperative post-l
 
 ## Messaging Events
 
-Subscribe to postback button clicks from the Zendesk messaging widget.
+Subscribe to postback button clicks from the Messaging widget.
 The \`actionName\` is the button's display text, not a programmatic identifier.
 
 **Permission:** \`events:messaging\`
@@ -3922,6 +4229,23 @@ await capabilities.identity.extend({ verified: true })
 useIdentityEvent('refresh', (event) => {
   console.log('verified =>', event.data.state.user?.metadata?.verified)
 })
+`,
+  "messaging.send": `
+// Send a message into the active conversation bound to this Instance.
+// Requires the 'messaging:send' permission. The author label rendered above
+// outbound messages is set per-Instance by the admin (Instance settings
+// messagingDisplayName); falls back to extension.manifest.name when blank.
+const [send, { loading, error }] = useMessaging()
+const result = await send({ kind: 'text', body: 'Hello from the extension' })
+
+// Actionable errors throw + populate state.error: 'invalid_message' (bad payload),
+// 'rate_limited' (slow down), 'upstream_error' (transient \u2014 retry). Branch in
+// catch / on state.error to show UX.
+// Host-handled cases ('no_conversation' / 'reauth_required' / 'forbidden')
+// resolve to null without throwing; the SDK logs a breadcrumb and the host
+// surfaces remediation to admins (e.g. dashboard Reconnect UI). Extensions
+// can pre-empt 'no_conversation' via useContextData().messaging?.conversationId.
+if (error === 'rate_limited') { /* show "slow down" UI */ }
 `
 };
 var EVENT_SNIPPETS = {
@@ -4575,6 +4899,13 @@ var SKILLS = [
     scopes: ["docs"],
     content: () => generateCookbookEvents()
   },
+  {
+    id: "cookbook-messaging",
+    description: "Cookbook: per-kind example payloads (text / image / file / carousel) and action types (reply / link / postback / locationRequest) for the messaging.send capability. Use when wiring the useMessaging hook or composing outbound conversation messages.",
+    type: "knowledge",
+    scopes: ["docs"],
+    content: () => generateCookbookMessaging()
+  },
   {
     id: "marketplace-listing",
     description: "Marketplace listing reference: the listing fields (icon, screenshots, description, categories), Public vs Protected visibility, and the two-stage review process (bundle scan + security review + approval). Use when publishing a deployed extension to the marketplace.",
@@ -5044,6 +5375,43 @@ export function Content() {
       <ui.Text className="text-xs">{lastEvent ?? 'No activity yet'}</ui.Text>
     </Surface>
   )
+}`,
+  "messaging.send": `import { useMessaging, useContextData, Surface, ui } from '@stackable-labs/sdk-extension-react'
+
+// Requires 'messaging:send' permission. send() throws on actionable errors
+// (state.error holds the typed code); resolves to null on host-handled cases.
+export function Content() {
+  const { messaging } = useContextData()
+  const [send, { loading, error }] = useMessaging()
+  // Proactive gate: skip the call when there's no conversation \u2014 avoids the
+  // host-handled no_conversation log + null return.
+  const canSend = !!messaging?.conversationId
+
+  const onSayHello = async () => {
+    try {
+      await send({
+        kind: 'text',
+        body: 'Hello from the extension',
+        actions: [
+          { type: 'reply', label: 'Sounds good', payload: 'ACK' },
+          { type: 'reply', label: 'Maybe later', payload: 'DEFER' },
+        ],
+      })
+    } catch {
+      // error holds the typed SendMessageActionableErrorCode
+    }
+  }
+
+  return (
+    <Surface id="slot.content">
+      <ui.Stack direction="column" gap="2" className="p-3">
+        <ui.Button onClick={onSayHello} disabled={loading || !canSend}>Say hello</ui.Button>
+        {(error === 'rate_limited') && <ui.Alert variant="warning">Slow down \u2014 sent too many.</ui.Alert>}
+        {(error === 'upstream_error') && <ui.Alert variant="error">Send failed \u2014 please try again.</ui.Alert>}
+        {(error === 'invalid_message') && <ui.Alert variant="error">Send failed \u2014 message format invalid.</ui.Alert>}
+      </ui.Stack>
+    </Surface>
+  )
 }`
 };
 
@@ -5135,7 +5503,22 @@ await capabilities.identity.extend({ verified: true })
 // Consumer side \u2014 same or sibling extension reacts via identity:refresh
 useIdentityEvent('refresh', (event) => {
   console.log('verified =>', event.data.state.user?.metadata?.verified)
-})`
+})`,
+  "messaging.send": `// Send a message into the active conversation bound to this Instance.
+// Requires the 'messaging:send' permission. The author label rendered above
+// outbound messages is set per-Instance by the admin (Instance settings
+// messagingDisplayName); falls back to extension.manifest.name when blank.
+const [send, { loading, error }] = useMessaging()
+const result = await send({ kind: 'text', body: 'Hello from the extension' })
+
+// Actionable errors throw + populate state.error: 'invalid_message' (bad payload),
+// 'rate_limited' (slow down), 'upstream_error' (transient \u2014 retry). Branch in
+// catch / on state.error to show UX.
+// Host-handled cases ('no_conversation' / 'reauth_required' / 'forbidden')
+// resolve to null without throwing; the SDK logs a breadcrumb and the host
+// surfaces remediation to admins (e.g. dashboard Reconnect UI). Extensions
+// can pre-empt 'no_conversation' via useContextData().messaging?.conversationId.
+if (error === 'rate_limited') { /* show "slow down" UI */ }`
 };
 var EVENT_SNIPPETS2 = {
   "events:identity": `import { useIdentityEvent, Surface, ui } from '@stackable-labs/sdk-extension-react'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackable-labs/mcp-app-extension",
-  "version": "1.28.0",
+  "version": "1.30.0",
   "type": "module",
   "bin": {
     "mcp-app-extension": "./dist/index.js"