@flamingo-stack/openframe-frontend-core 0.0.532 → 0.0.533

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flamingo-stack/openframe-frontend-core",
-  "version": "0.0.532",
+  "version": "0.0.533",
   "description": "Shared design system and components for all Flamingo platforms",
   "type": "module",
   "main": "./dist/index.js",

package/src/chat-protocol/__tests__/__snapshots__/nats-decoder-golden.test.ts.snap

@@ -263,6 +263,76 @@ exports[`decodeNatsChunk — golden corpus > maps the full recorded corpus to no
     "text": "",
     "type": "guide-delta",
   },
+  "guide_frame_approval_batch": {
+    "approvalType": "chat",
+    "origin": "guide",
+    "requestId": "batch:prop-1",
+    "status": "pending",
+    "toolCalls": [
+      {
+        "requiresApproval": true,
+        "toolCallArguments": null,
+        "toolExecutionRequestId": "prop-1",
+        "toolName": "create_ticket",
+        "toolTitle": "Open a ticket",
+      },
+    ],
+    "type": "approval-request",
+  },
+  "guide_frame_approval_request": {
+    "approvalType": "create_ticket",
+    "command": "Open a support ticket",
+    "fields": [
+      {
+        "label": "Subject",
+        "value": "Agent will not enroll",
+      },
+    ],
+    "origin": "guide",
+    "requestId": "prop-1",
+    "status": "pending",
+    "type": "approval-request",
+  },
+  "guide_frame_decision_resolved": {
+    "ok": true,
+    "origin": "guide",
+    "requestId": "prop-1",
+    "status": "approved",
+    "type": "approval-resolved",
+    "willAutoContinue": false,
+  },
+  "guide_frame_metadata": {
+    "conversationId": "conv-1",
+    "origin": "guide",
+    "type": "metadata",
+  },
+  "guide_frame_payload_array": null,
+  "guide_frame_payload_empty": null,
+  "guide_frame_payload_not_object": null,
+  "guide_frame_routing": null,
+  "guide_frame_status_thinking": null,
+  "guide_frame_text_leading": {
+    "text": "I'll look that up in the docs.",
+    "type": "guide-delta",
+  },
+  "guide_frame_text_wins": {
+    "text": "body",
+    "type": "guide-delta",
+  },
+  "guide_frame_thinking": {
+    "text": "The user asked about <policies> setup",
+    "type": "thinking-delta",
+  },
+  "guide_frame_tool_error": {
+    "title": "Could not reach HubSpot",
+    "type": "error",
+  },
+  "guide_frame_usage_start": null,
+  "guide_frame_with_seq": {
+    "seq": 77,
+    "text": "Checking the docs…",
+    "type": "guide-delta",
+  },
   "guide_missing_text": null,
   "message_end": {
     "type": "turn-end",

package/src/chat-protocol/__tests__/nats-decoder-golden.test.ts

@@ -11,7 +11,8 @@
  */
 
 import { describe, it, expect } from 'vitest'
-import { decodeNatsChunk } from '../nats-decoder'
+import type { ChatStreamEvent } from '../events'
+import { decodeNatsChunk, guideEventForNats } from '../nats-decoder'
 
 /** Recorded corpus of realistic NATS chunk shapes, keyed by scenario name. */
 const CORPUS: Record<string, unknown> = {
@@ -29,6 +30,69 @@ const CORPUS: Record<string, unknown> = {
   guide_empty_string: { type: 'GUIDE', text: '' },
   guide_missing_text: { type: 'GUIDE' },
 
+  // GUIDE frames — hub frames the agent re-streams verbatim inside the same
+  // chunk type, under `payload`. They cross over by DEFAULT; only the dialog's
+  // own accounting and phase stop at the seam. See `guideEventForNats`.
+  guide_frame_text_leading: {
+    type: 'GUIDE',
+    payload: { kind: 'text-leading', text: "I'll look that up in the docs." },
+  },
+  guide_frame_thinking: {
+    type: 'GUIDE',
+    payload: { kind: 'thinking-delta', text: 'The user asked about <policies> setup' },
+  },
+  guide_frame_tool_error: {
+    type: 'GUIDE',
+    payload: { kind: 'tool_error', message: 'Could not reach HubSpot' },
+  },
+  // Dropped: would blank the model badge / relabel the turn with the hub's model.
+  guide_frame_routing: {
+    type: 'GUIDE',
+    payload: { kind: 'routing', routedComplexity: 'deep', routedModel: 'claude-x', routedThinkingBudget: 8000 },
+  },
+  guide_frame_metadata: {
+    type: 'GUIDE',
+    payload: { model: 'claude-x', modelLabel: 'Guide model', conversationId: 'conv-1' },
+  },
+  // Dropped: the dialog owns its own phase and token accounting.
+  guide_frame_status_thinking: { type: 'GUIDE', payload: { status: 'thinking' } },
+  guide_frame_usage_start: { type: 'GUIDE', payload: { kind: 'usage', stage: 'start', input_tokens: 12 } },
+  // Crosses over stamped `origin: 'guide'` — the marker that keeps the card
+  // inline and sends its buttons to the hub's confirm route.
+  guide_frame_approval_request: {
+    type: 'GUIDE',
+    payload: {
+      kind: 'approval_request',
+      proposalId: 'prop-1',
+      toolName: 'create_ticket',
+      title: 'Open a support ticket',
+      fields: [{ label: 'Subject', value: 'Agent will not enroll' }],
+    },
+  },
+  guide_frame_approval_batch: {
+    type: 'GUIDE',
+    payload: {
+      kind: 'approval_batch',
+      batchId: 'batch:prop-1',
+      proposals: [{ proposalId: 'prop-1', toolName: 'create_ticket', title: 'Open a ticket' }],
+    },
+  },
+  guide_frame_decision_resolved: {
+    type: 'GUIDE',
+    payload: { kind: 'decision_resolved', proposalId: 'prop-1', ok: true, action: 'approved', willAutoContinue: false },
+  },
+  // Malformed payloads degrade to a no-op, like every other chunk shape.
+  guide_frame_payload_not_object: { type: 'GUIDE', payload: 'text-leading' },
+  guide_frame_payload_array: { type: 'GUIDE', payload: [{ kind: 'text-leading', text: 'hi' }] },
+  guide_frame_payload_empty: { type: 'GUIDE', payload: {} },
+  // `text` wins when both are present — the body is what the agent persists.
+  guide_frame_text_wins: { type: 'GUIDE', text: 'body', payload: { kind: 'thinking-delta', text: 'ignored' } },
+  guide_frame_with_seq: {
+    type: 'GUIDE',
+    streamSeq: 77,
+    payload: { kind: 'text-leading', text: 'Checking the docs…' },
+  },
+
   // ASK — the guide-routing clarification card. `text` is the intro sentence
   // riding the same chunk; a card without a question or without usable options
   // is dropped (nothing the user could answer).
@@ -280,6 +344,49 @@ describe('decodeNatsChunk — golden corpus', () => {
   })
 })
 
+describe('guideEventForNats — the two kernels reconciled', () => {
+  // The property that matters for maintenance: `leading-frames` is the ONE
+  // place a hub frame kind is taught to the client, so an event kind that
+  // reaches this adapter must cross over WITHOUT an edit here. These use event
+  // types the frame table cannot produce today on purpose — they stand in for
+  // whatever the hub ships next.
+  it('passes an unfamiliar event through unchanged', () => {
+    const ask: ChatStreamEvent = {
+      type: 'ask',
+      question: 'Which workspace?',
+      options: [{ label: 'Acme' }],
+    }
+    expect(guideEventForNats(ask)).toEqual(ask)
+  })
+
+  it('stamps origin on the events that carry it, so the card routes to the hub', () => {
+    expect(
+      guideEventForNats({ type: 'approval-request', requestId: 'prop-1', approvalType: 'create_ticket' }),
+    ).toMatchObject({ approvalType: 'create_ticket', origin: 'guide' })
+    expect(guideEventForNats({ type: 'approval-resolved', requestId: 'prop-1', status: 'approved' })).toMatchObject({
+      origin: 'guide',
+    })
+  })
+
+  it('stops the events the agent owns for this dialog', () => {
+    expect(guideEventForNats({ type: 'usage', stage: 'start', input_tokens: 10 })).toBeNull()
+    expect(guideEventForNats({ type: 'status', phase: 'thinking' })).toBeNull()
+    expect(
+      guideEventForNats({ type: 'token-usage', inputTokensSize: 1, outputTokensSize: 2, totalTokensSize: 3, contextSize: 4 }),
+    ).toBeNull()
+    expect(guideEventForNats({ type: 'dialog-closed' })).toBeNull()
+  })
+
+  it('keeps metadata only for the hub conversation id every confirm must quote back', () => {
+    expect(guideEventForNats({ type: 'metadata', conversationId: 'conv-1', modelName: 'hub-model' })).toEqual({
+      type: 'metadata',
+      conversationId: 'conv-1',
+      origin: 'guide',
+    })
+    expect(guideEventForNats({ type: 'metadata', modelName: 'hub-model' })).toBeNull()
+  })
+})
+
 describe('decodeNatsChunk — seq envelope', () => {
   it('lifts a numeric JetStream `streamSeq` into `seq`, and omits it otherwise (snapshot)', () => {
     expect({

package/src/chat-protocol/confirm-tool.ts

@@ -0,0 +1,67 @@
+/**
+ * The hub's confirm-tool contract — request shape and error envelope.
+ *
+ * Resolving a Product Guide proposal is a POST to `endpoints.approvalToolUrl`
+ * whose response is an ordinary guide stream (a `decision_resolved` frame, then
+ * the hub's auto-continuation). Two callers make that call today: the SSE chat
+ * adapter, and any host replaying the same route into a different transport's
+ * conversation (the product app resolves guide cards inside a NATS Mingo
+ * dialog). They MUST send byte-identical bodies — a proposal is single-use, so a
+ * caller that drifts on a field name does not degrade, it fails the write — and
+ * they must surface the same server copy, because the hub's errors are written
+ * for the end user ("This approval expired — ask again to get a fresh one").
+ *
+ * Hence both live here rather than at either call site.
+ *
+ * Server-safe: no React, no browser APIs.
+ */
+
+/** What the user did with the card. */
+export type ApprovalToolAction = 'approve' | 'reject'
+
+/** Client-side shape of a confirm; `buildConfirmToolBody` renames it to the
+ *  wire's own casing so no caller hand-writes `proposal_id`. */
+export interface ConfirmToolRequest {
+  /** The hub-minted proposal id carried by the card. */
+  proposalId: string
+  action: ApprovalToolAction
+  /**
+   * The hub's conversation id, quoted back verbatim. The hub rejects a confirm
+   * without it: a proposal only means something inside the conversation that
+   * minted it.
+   */
+  conversationId: string | null | undefined
+}
+
+/** Build the confirm-tool request body. The ONE place that knows the wire
+ *  spells the id `proposal_id` while everything else is camelCase. */
+export function buildConfirmToolBody(request: ConfirmToolRequest): Record<string, unknown> {
+  return {
+    proposal_id: request.proposalId,
+    action: request.action,
+    conversationId: request.conversationId,
+  }
+}
+
+/**
+ * Pull the user-facing copy out of a failed chat/confirm response.
+ *
+ * The route-base envelope is `{error, code}`; `error` is written for the end
+ * user, so it beats any status-code copy the client could invent. Returns null
+ * when the body is not that envelope (HTML error page, empty body, gateway
+ * response) — the caller then supplies its own generic line.
+ *
+ * Consumes the body: call it once, on a response you have already decided is a
+ * failure.
+ */
+export async function readServerErrorMessage(response: {
+  json: () => Promise<unknown>
+}): Promise<string | null> {
+  try {
+    const body = (await response.json()) as { error?: unknown } | null
+    if (typeof body?.error === 'string' && body.error.length > 0) return body.error
+  } catch {
+    /* non-JSON error body — the caller falls through to its generic copy */
+  }
+  return null
+}

package/src/chat-protocol/decode.ts

@@ -35,6 +35,9 @@
 
 import { FRAME_TERMINATOR, END_OF_LEADING, TRAILER_SENTINEL } from './frames'
 import type { ChatStreamEvent } from './events'
+// The frame table is SHARED with the NATS decoder — guide answers re-stream the
+// hub's frames verbatim inside `GUIDE` chunks — so it lives in its own module.
+import { mapLeadingFrame } from './leading-frames'
 
 export interface SseFrameDecoder {
   /** Feed raw response bytes; returns the events they produced. */
@@ -49,159 +52,10 @@ export interface SseFrameDecoder {
   end(): ChatStreamEvent[]
 }
 
-/**
- * Escape `<` so markdown renderers that pass HTML through (rehypeRaw)
- * don't treat XML-like tokens in Claude's thinking output as elements.
- * `<` → `&lt;` preserves the visible character without breaking
- * blockquote `>` markers. Per-character, so it distributes over
- * concatenation: escape(a + b) === escape(a) + escape(b) — callers may
- * apply it per-delta or on the accumulated string interchangeably.
- */
-export function escapeThinkingTags(text: string): string {
-  return text.replace(/</g, '&lt;')
-}
-
-/**
- * Map one parsed leading frame to normalized events, replicating the
- * legacy parser's else-if chain ORDER and its exact truthiness/typeof
- * gates. Frames that matched a branch but failed its inner validation
- * (e.g. `routing` without a string `routedComplexity`) produce NO event,
- * exactly like the legacy no-op.
- */
-function mapLeadingFrame(meta: any, out: ChatStreamEvent[]): void {
-  if (meta.status === 'thinking') {
-    out.push({ type: 'status', phase: 'thinking' })
-  } else if (meta.kind === 'thinking-delta' && typeof meta.text === 'string') {
-    // Wire is ALREADY delta — emit verbatim, append-only contract.
-    out.push({ type: 'thinking-delta', text: meta.text })
-  } else if (meta.kind === 'usage' && meta.stage === 'start') {
-    out.push({
-      type: 'usage',
-      stage: 'start',
-      input_tokens: meta.input_tokens,
-      cache_read_input_tokens: meta.cache_read_input_tokens,
-      cache_creation_input_tokens: meta.cache_creation_input_tokens,
-    })
-  } else if (meta.kind === 'decision_resolved' && typeof meta.action === 'string') {
-    const status = meta.action === 'rejected' ? 'rejected' : 'approved'
-    const toolName = typeof meta.tool_name === 'string' ? meta.tool_name : undefined
-    const result = meta.result ?? null
-    const card = meta.card ?? null
-    out.push({
-      type: 'approval-resolved',
-      status,
-      ok: meta.ok === true,
-      willAutoContinue: meta.willAutoContinue === true,
-      ...(toolName ? { toolName } : {}),
-      ...(result ? { result } : {}),
-      ...(card?.marker ? { marker: card.marker } : {}),
-      ...(card?.ref ? { cardRef: card.ref } : {}),
-      ...(card?.type ? { cardType: card.type } : {}),
-      ...(typeof meta.receiptText === 'string' ? { receiptText: meta.receiptText } : {}),
-      requestId: typeof meta.proposalId === 'string' ? meta.proposalId : undefined,
-    })
-  } else if (meta.kind === 'approval_batch' && meta.batchId && Array.isArray(meta.proposals)) {
-    // Server-grouped multi-proposal turn → ONE batch event carrying a
-    // tool-call row per proposal. `toolExecutionRequestId` is the row's
-    // PROPOSAL id (each row resolves through its own per-proposal
-    // confirm); the batch's `requestId` is the stable anchor the shell
-    // uses for status flips. Field rows ride as the row's expandable
-    // args so per-proposal detail stays reachable inside the batch.
-    const toolCalls = (meta.proposals as Array<Record<string, any>>)
-      .filter((p) => p && typeof p.proposalId === 'string')
-      .map((p) => {
-        const rawFields = Array.isArray(p.fields)
-          ? (p.fields as Array<{ label?: string; value?: string }>).filter(
-              (f) => f && f.label && f.value,
-            )
-          : []
-        // Prefer human-readable identity labels for the row's
-        // disambiguator; opaque-id labels ("Task", "Ticket") only as
-        // the last-resort first field.
-        const detail =
-          rawFields.find((f) => /^(title|subject|name)$/i.test(String(f.label))) ??
-          rawFields[0]
-        const base =
-          typeof p.title === 'string' && p.title.length > 0 ? p.title : String(p.toolName ?? 'Tool call')
-        return {
-          toolExecutionRequestId: String(p.proposalId),
-          toolName: String(p.toolName ?? 'tool'),
-          toolTitle: detail ? `${base} — ${detail.value}` : base,
-          requiresApproval: true,
-          toolCallArguments:
-            rawFields.length > 0
-              ? Object.fromEntries(rawFields.map((f) => [String(f.label), String(f.value)]))
-              : null,
-        }
-      })
-    if (toolCalls.length > 0) {
-      out.push({
-        type: 'approval-request',
-        requestId: String(meta.batchId),
-        approvalType: 'chat',
-        toolCalls,
-        status: 'pending',
-      })
-    }
-  } else if (meta.kind === 'approval_request' && meta.proposalId) {
-    const proposalId = String(meta.proposalId)
-    const toolName = String(meta.toolName ?? 'tool')
-    const headline =
-      typeof meta.title === 'string' && meta.title.length > 0 ? meta.title : toolName
-    const rawFields = Array.isArray(meta.fields)
-      ? (meta.fields as Array<{ label?: string; value?: string }>)
-      : []
-    const fields: Array<{ label: string; value: string }> = []
-    for (const f of rawFields) {
-      if (!f || !f.label || !f.value) continue
-      fields.push({ label: f.label, value: f.value })
-    }
-    out.push({
-      type: 'approval-request',
-      requestId: proposalId,
-      approvalType: toolName,
-      command: headline,
-      fields,
-      status: 'pending',
-    })
-  } else if (meta.kind === 'text-leading' && typeof meta.text === 'string') {
-    out.push({ type: 'text-delta', text: meta.text, leading: true })
-  } else if (meta.kind === 'tool_error') {
-    const msg =
-      typeof meta.message === 'string' && meta.message.length > 0
-        ? meta.message
-        : 'Could not complete the requested action right now.'
-    out.push({ type: 'error', title: msg })
-  } else if (meta.kind === 'routing') {
-    if (typeof meta.routedComplexity === 'string') {
-      out.push({
-        type: 'metadata',
-        routing: {
-          routedComplexity: meta.routedComplexity,
-          ...(typeof meta.routedModel === 'string' ? { routedModel: meta.routedModel } : {}),
-          routedThinkingBudget:
-            typeof meta.routedThinkingBudget === 'number' ? meta.routedThinkingBudget : null,
-        },
-      })
-    }
-  } else {
-    // Catch-all metadata-ish frame. Raw values pass through UNVALIDATED
-    // (possibly undefined) so the consumer can replicate the legacy
-    // presence/truthiness gates exactly — including the `model`-presence
-    // trigger whose value is never stored.
-    out.push({
-      type: 'metadata',
-      sources: meta.sources,
-      refs: meta.refs,
-      provider: meta.provider,
-      modelLabel: meta.modelLabel,
-      modelName: meta.model,
-      contextWindowMaxTokens: meta.contextWindowMaxTokens,
-      scrollAnchor: meta.scrollAnchor,
-      conversationId: meta.conversationId,
-    })
-  }
-}
+// `escapeThinkingTags` moved to `./leading-frames` alongside the frame table,
+// and is re-exported here: consumers have imported it from this module since it
+// was written, and the `chat-protocol` barrel re-exports it from here.
+export { escapeThinkingTags } from './leading-frames'
 
 export function createSseFrameDecoder(): SseFrameDecoder {
   const textDecoder = new TextDecoder()

package/src/chat-protocol/events.ts

@@ -138,6 +138,37 @@ export interface ApprovalRequestEvent extends ChatStreamEventBase {
   fields?: ApprovalRequestField[]
   toolCalls?: ApprovalToolCall[]
   status?: 'pending'
+  /** Set when the card came from a Product Guide frame — see {@link GuideOrigin}. */
+  origin?: GuideOrigin
+}
+
+/**
+ * Marks an event whose payload is a Product Guide frame, whatever transport
+ * carried it. It exists because ONE stream can now mix both worlds: the agent
+ * re-streams the hub's frames into a NATS dialog, so a card typed the hub's way
+ * (`approvalType` = the tool name, resolved through the hub's confirm route)
+ * travels beside cards typed the agent's way (`approvalType` = an approval TIER
+ * routed to human escalation).
+ *
+ * Consumers read it to keep the guide half behaving exactly as it does in the
+ * hub's own chat — NOT to give it special treatment. Without it the NATS kernel
+ * would have to guess from `approvalType`, and every tool the hub adds would
+ * silently fall into the escalation path.
+ */
+export type GuideOrigin = 'guide'
+
+/** The only value of {@link GuideOrigin}. Lives beside the type, and beside the
+ *  predicate below, because both decoders and every consumer that branches on
+ *  provenance must compare against the same token — a bare `'guide'` literal
+ *  typo silently disables the branch instead of failing to compile. */
+export const GUIDE_ORIGIN: GuideOrigin = 'guide'
+
+/** True for anything stamped as coming from the Product Guide — a stream event
+ *  or the `data` of a segment built from one. */
+export function isGuideOrigin(
+  source: { origin?: GuideOrigin | string } | null | undefined,
+): boolean {
+  return source?.origin === GUIDE_ORIGIN
 }
 
 /** An approval request was resolved (SSE `decision_resolved` frame /
@@ -158,6 +189,8 @@ export interface ApprovalResolvedEvent extends ChatStreamEventBase {
   marker?: string
   result?: DecisionResolvedFrame['result']
   willAutoContinue?: boolean
+  /** Set when the resolution came from a Product Guide frame — see {@link GuideOrigin}. */
+  origin?: GuideOrigin
 }
 
 /** The client is offered a handoff of this ticket to a human technician
@@ -245,6 +278,13 @@ export interface ChatMetadataEvent extends ChatStreamEventBase {
     routedModel?: string
     routedThinkingBudget: number | null
   }
+  /**
+   * Set when the metadata came from a Product Guide frame — see
+   * {@link GuideOrigin}. Such an event carries ONLY `conversationId`: it exists
+   * to record the hub's conversation id (every confirm-tool call must quote it
+   * back), NOT to describe the dialog's model, which stays the agent's.
+   */
+  origin?: GuideOrigin
 }
 
 /** SSE usage frames — raw wire keys (snake_case) preserved. */

package/src/chat-protocol/index.ts

@@ -14,6 +14,9 @@ export * from './events'
 export * from './encode'
 export * from './decode'
 export * from './nats-decoder'
+// The hub's confirm-tool request/error contract — shared by every transport
+// that resolves a Product Guide proposal.
+export * from './confirm-tool'
 // Cross-repo IP bucket-key normalizer (producer app + consumer hub share it).
 export * from './ip-normalize'
 // Cross-repo env-flag predicate — the trust assertion that gates the IP