@flamingo-stack/openframe-frontend-core 0.0.458-snapshot.20260720215024 → 0.0.458

package/src/chat-protocol/encode.ts

@@ -1,71 +0,0 @@
-/**
- * SSE wire-protocol encoders — the emit side of the framing contract in
- * `./frames.ts`. Server-safe (TextEncoder only). The hub's stream route
- * consumes these so emitter and decoder can never drift.
- */
-
-import {
-  FRAME_TERMINATOR,
-  END_OF_LEADING,
-  TRAILER_SENTINEL,
-  type SseLeadingFrame,
-  type SseTrailingUsageFrame,
-} from './frames'
-
-const encoder = new TextEncoder()
-
-/** Matches every framing sentinel byte: `\0`, `\x1E`, `\x1F`. THE one
- *  regex — `stripSentinelBytes` is its only consumer. */
-const SENTINEL_BYTES_RE = /[\u0000\u001E\u001F]/g
-
-/**
- * Remove the SSE framing sentinel bytes (`\0`, `\x1E`, `\x1F`) from model
- * text. Exported as a STANDALONE helper — not just folded into
- * `encodeTextDelta` — because producers must strip at the point where they
- * first take custody of the text, BEFORE any local accumulation.
- *
- * Concretely: the hub's `claude-util.ts` accumulates `state.answerText` for
- * persistence + telemetry. If stripping only happened at encode time, the
- * persisted/telemetered answer would diverge, character for character, from
- * the bytes the user actually received whenever the model echoes a control
- * byte. Both sides call this, so there is exactly ONE definition of "which
- * bytes are framing" in the whole system — do not re-declare the regex.
- *
- * Idempotent and per-character, so it distributes over concatenation:
- * `strip(a + b) === strip(a) + strip(b)` — safe to apply per-delta or on the
- * accumulated string interchangeably.
- */
-export function stripSentinelBytes(text: string): string {
-  return text.replace(SENTINEL_BYTES_RE, '')
-}
-
-/** Encode one leading frame: JSON + `\0` terminator. */
-export function encodeLeadingFrame(frame: SseLeadingFrame): Uint8Array {
-  return encoder.encode(JSON.stringify(frame) + FRAME_TERMINATOR)
-}
-
-/** Encode the single `\x1E` end-of-leading-frames sentinel. */
-export function encodeEndOfLeading(): Uint8Array {
-  return encoder.encode(END_OF_LEADING)
-}
-
-/**
- * Encode a raw answer-text delta. STRIPS the framing sentinel bytes via
- * `stripSentinelBytes` so model-echoed control bytes can no longer
- * mis-frame the stream (a literal `\x1F` in the answer used to flip the
- * client into trailer mode and swallow the rest of the answer PLUS the real
- * usage trailer — characterized by golden fixture (d)). Forward-looking
- * encoder fix only; the decoder's behavior is unchanged.
- *
- * Producers that ALSO accumulate the text locally (persistence, telemetry)
- * must call `stripSentinelBytes` on their own copy — see its docblock.
- */
-export function encodeTextDelta(text: string): Uint8Array {
-  return encoder.encode(stripSentinelBytes(text))
-}
-
-/** Encode the trailing usage frame: `\x1F` + JSON, no terminator
- *  (runs to stream end). */
-export function encodeTrailingUsageFrame(frame: SseTrailingUsageFrame): Uint8Array {
-  return encoder.encode(TRAILER_SENTINEL + JSON.stringify(frame))
-}

package/src/chat-protocol/env-flag.ts

@@ -1,39 +0,0 @@
-/**
- * `envFlagEnabled` — THE cross-repo predicate for reading a boolean env flag.
- *
- * WHY IT LIVES HERE: the same flag is read on BOTH sides of the guide-chat
- * seam and each side had grown its own reading of it. The hub parsed the
- * value (`'0'` / `'false'` / `'off'` mean OFF); the producing app used bare
- * `Boolean(process.env.X)`, under which every non-empty string — including
- * `'0'` and `'false'` — is TRUE.
- *
- * That divergence failed OPEN on the one flag that gates a security boundary.
- * `TRUSTED_INGRESS_SETS_REAL_IP` is an operator's assertion that a reverse
- * proxy OVERWRITES the client-IP headers; without it those headers are
- * attacker-writable and must not be read. An operator writing `=0` to mean
- * "off" got the hub honoring that while the producer read `x-real-ip` /
- * `x-forwarded-for` anyway and forwarded the value as `x-chat-ip`, which the
- * hub then trusts verbatim under the service token. A rate-limit-bucket
- * spoof, reachable through a plausible operator typo.
- *
- * Both repos already depend on this package and `./chat-protocol` is its
- * server-safe subpath (no React, no browser APIs), so this is the one place
- * both sides can share — same reasoning that moved `normalizeIpForBucketKey`
- * here. Keep it as ONE definition: a second copy is what caused the drift.
- *
- * Contract:
- *   - unset, empty, or whitespace-only  → `false`;
- *   - `'0'`, `'false'`, `'off'`         → `false` (case- and
- *     surrounding-whitespace-insensitive);
- *   - any other non-empty value         → `true`.
- *
- * `process.env` is read PER CALL, never module-hoisted, so tests, preview and
- * prod all observe the live value rather than whatever was present at
- * module-eval time.
- */
-export function envFlagEnabled(name: string): boolean {
-  const raw = process.env[name]
-  if (!raw) return false
-  const v = raw.trim().toLowerCase()
-  return v !== '' && v !== '0' && v !== 'false' && v !== 'off'
-}

package/src/chat-protocol/events.ts

@@ -1,228 +0,0 @@
-/**
- * Normalized chat stream events — the transport-agnostic event union BOTH
- * decoders (SSE byte framing in `./decode.ts`, NATS chunks in
- * `./nats-decoder.ts`) emit. Phase 3 of the chat unification makes the
- * reducer consume these directly; today the SSE adapter maps them back to
- * legacy `MessageSegment` yields.
- *
- * Server-safe: no React, no browser APIs.
- */
-
-// The wire-frame shapes these events carry through are defined ONCE in
-// `./frames.ts` — reuse them here rather than restating their fields.
-import type {
-  ApprovalRequestField,
-  DecisionResolvedFrame,
-  UsageTelemetry,
-} from './frames'
-
-/** Optional envelope on every event. `seq` carries the transport's
- *  stream sequence (JetStream `streamSeq` on NATS; unused on SSE). */
-interface ChatStreamEventBase {
-  seq?: number
-}
-
-/** Stream entered answer-text mode (SSE: the `\x1E` sentinel or the
- *  JSON-parse-failure fallback; NATS: MESSAGE_START).
- *  `implicit` is true ONLY for the SSE fallback path where a
- *  non-JSON leading buffer flips straight into text mode — consumers
- *  that flush coalesced thinking on turn-start must SKIP the flush for
- *  implicit starts (legacy adapter parity: the fallback path never
- *  flushed pending thinking before the text). */
-export interface TurnStartEvent extends ChatStreamEventBase {
-  type: 'turn-start'
-  implicit?: boolean
-}
-
-export interface TurnEndEvent extends ChatStreamEventBase {
-  type: 'turn-end'
-}
-
-/** Answer text delta. `leading: true` marks SSE `text-leading` frames
- *  (model preamble prose emitted BEFORE the tool approval card). */
-export interface TextDeltaEvent extends ChatStreamEventBase {
-  type: 'text-delta'
-  text: string
-  leading?: boolean
-}
-
-/** Thinking delta — APPEND-ONLY contract: each event carries the next
- *  verbatim slice; consumers accumulate. Decoders never diff. */
-export interface ThinkingDeltaEvent extends ChatStreamEventBase {
-  type: 'thinking-delta'
-  text: string
-}
-
-export interface StatusEvent extends ChatStreamEventBase {
-  type: 'status'
-  phase: 'thinking'
-}
-
-/** NATS tool execution progress (EXECUTING_TOOL / EXECUTED_TOOL). */
-export interface ToolExecutionEvent extends ChatStreamEventBase {
-  type: 'tool-execution'
-  data: {
-    type: 'EXECUTING_TOOL' | 'EXECUTED_TOOL'
-    integratedToolType: string
-    toolFunction: string
-    toolTitle?: string
-    parameters?: Record<string, unknown>
-    result?: string
-    success?: boolean
-    toolExecutionRequestId?: string
-  }
-}
-
-/** Single tool call inside a batch approval request (NATS). */
-export interface ApprovalToolCall {
-  toolExecutionRequestId: string
-  toolName: string
-  toolTitle?: string
-  toolExplanation?: string
-  toolType?: string
-  requiresApproval: boolean
-  approvalType?: string | null
-  toolCallArguments?: Record<string, unknown> | null
-}
-
-/** A tool call awaits user approval. SSE fills `command`/`fields`
- *  (card-ready payload); NATS fills `command`/`explanation` or
- *  `toolCalls` (batch form). */
-export interface ApprovalRequestEvent extends ChatStreamEventBase {
-  type: 'approval-request'
-  requestId: string
-  /** SSE: the write tool's name. NATS: approval tier (USER/ADMIN/…). */
-  approvalType?: string
-  command?: string
-  explanation?: string
-  fields?: ApprovalRequestField[]
-  toolCalls?: ApprovalToolCall[]
-  status?: 'pending'
-}
-
-/** An approval request was resolved (SSE `decision_resolved` frame /
- *  NATS APPROVAL_RESULT chunk). */
-export interface ApprovalResolvedEvent extends ChatStreamEventBase {
-  type: 'approval-resolved'
-  requestId?: string
-  status: 'approved' | 'rejected'
-  ok?: boolean
-  toolName?: string
-  approvalType?: string
-  resolvedByName?: string | null
-  receiptText?: string
-  /** Inline post-approve card: the ref payload + its documentType +
-   *  the `[card://…]` marker (SSE only). */
-  cardRef?: unknown
-  cardType?: string
-  marker?: string
-  result?: DecisionResolvedFrame['result']
-  willAutoContinue?: boolean
-}
-
-/** Per-turn metadata. Raw wire values pass through UNVALIDATED — the
- *  consumer replicates the legacy truthiness/typeof gates (so a
- *  malformed frame degrades identically to the pre-SSOT parser). */
-export interface ChatMetadataEvent extends ChatStreamEventBase {
-  type: 'metadata'
-  provider?: string | null
-  modelLabel?: string | null
-  /** Raw model id (SSE `meta.model`; NATS `modelName`). */
-  modelName?: string | null
-  contextWindowMaxTokens?: number | null
-  sources?: unknown
-  refs?: unknown
-  scrollAnchor?: unknown
-  routing?: {
-    routedComplexity: string
-    routedModel?: string
-    routedThinkingBudget: number | null
-  }
-}
-
-/** SSE usage frames — raw wire keys (snake_case) preserved. */
-export interface UsageEvent extends ChatStreamEventBase {
-  type: 'usage'
-  stage: 'start' | 'end'
-  input_tokens?: number
-  output_tokens?: number
-  cache_read_input_tokens?: number
-  cache_creation_input_tokens?: number
-  hit_rate_pct?: number
-  telemetry?: UsageTelemetry
-  /** Left OPAQUE on purpose: the consumer (`chat-stream-reducer`'s
-   *  `applySseUsage`) re-validates every nested field with the legacy
-   *  truthiness/typeof gates, so a malformed frame degrades identically
-   *  to the pre-SSOT parser. Typing it would imply guarantees the wire
-   *  does not make. */
-  breakdown?: unknown
-  debug?: unknown
-}
-
-/** NATS TOKEN_USAGE chunk (camelCase backend shape). */
-export interface TokenUsageEvent extends ChatStreamEventBase {
-  type: 'token-usage'
-  inputTokensSize: number
-  outputTokensSize: number
-  totalTokensSize: number
-  contextSize: number
-}
-
-export interface CompactionEvent extends ChatStreamEventBase {
-  type: 'compaction'
-  phase: 'start' | 'end'
-  summary?: string
-}
-
-export interface ErrorEvent extends ChatStreamEventBase {
-  type: 'error'
-  title: string
-  details?: string
-}
-
-/** Non-assistant message on the stream (NATS): the user's own message
- *  echo (`message-request`), an operator direct message, or a system
- *  line. */
-/**
- * Dialog participant owner type. The two members below are the ones clients
- * BRANCH ON (admin-vs-not decides echo dedup and author styling); the union
- * stays open (`string & {}`) because the wire may carry other roles that the
- * client treats as "not admin". Always compare against `CHAT_OWNER_ADMIN`,
- * never a bare `'ADMIN'` literal — a typo in a literal silently disables
- * dedup instead of failing to compile.
- */
-export type ChatOwnerType = 'ADMIN' | 'CLIENT' | (string & {})
-
-/** Canonical ADMIN owner-type token (see `ChatOwnerType`). */
-export const CHAT_OWNER_ADMIN = 'ADMIN'
-
-export interface ParticipantEvent extends ChatStreamEventBase {
-  type: 'participant'
-  kind: 'message-request' | 'direct-message' | 'system'
-  text: string
-  ownerType?: ChatOwnerType
-  displayName?: string
-  userId?: string
-  contextItems?: Array<{ type: string; id: string; label: string }>
-}
-
-export interface DialogClosedEvent extends ChatStreamEventBase {
-  type: 'dialog-closed'
-}
-
-export type ChatStreamEvent =
-  | TurnStartEvent
-  | TurnEndEvent
-  | TextDeltaEvent
-  | ThinkingDeltaEvent
-  | StatusEvent
-  | ToolExecutionEvent
-  | ApprovalRequestEvent
-  | ApprovalResolvedEvent
-  | ChatMetadataEvent
-  | UsageEvent
-  | TokenUsageEvent
-  | CompactionEvent
-  | ErrorEvent
-  | ParticipantEvent
-  | DialogClosedEvent

package/src/chat-protocol/frames.ts

@@ -1,238 +0,0 @@
-/**
- * SSE wire-protocol frame shapes — the byte-level contract between the
- * hub's chat stream emitter (`multi-platform-hub/lib/utils/claude-util.ts`)
- * and the lib's SSE decoder (`./decode.ts`).
- *
- * Wire format (custom byte framing, NOT standard SSE `data:` lines):
- *
- *   [JSON frame]\0 [JSON frame]\0 …  \x1E  <raw UTF-8 answer deltas>  \x1F [JSON usage trailer]
- *
- *   1. LEADING frames — each a JSON object terminated by `\0`
- *      (FRAME_TERMINATOR). Status, metadata, routing, live thinking
- *      deltas, usage:start, tool approval frames.
- *   2. ONE `\x1E` byte (END_OF_LEADING) — flips the stream into raw
- *      UTF-8 answer-text mode.
- *   3. `\x1F` (TRAILER_SENTINEL) + one JSON usage frame running to
- *      stream end (no terminator).
- *
- * Server-safe: no React, no browser APIs beyond TextEncoder/TextDecoder.
- */
-
-// =============================================================================
-// Sentinel constants
-// =============================================================================
-
-/** Terminates every leading JSON frame. */
-export const FRAME_TERMINATOR = '\0'
-/** Record Separator — end of leading frames, start of raw answer text. */
-export const END_OF_LEADING = '\x1E'
-/** Unit Separator — start of the trailing usage JSON frame. */
-export const TRAILER_SENTINEL = '\x1F'
-
-// =============================================================================
-// Routing types (moved verbatim from the hub's `lib/chat/wire-frames.ts`;
-// `RouteComplexity` is lib-local so the lib never imports hub code)
-// =============================================================================
-
-/** Server-side routing complexity tiers. Mirror of the hub's
- *  `lib/constants/ai-models.ts` union — kept as a lib-local literal type
- *  so the wire SSOT has zero hub imports. The DECODER accepts any string
- *  (older/newer servers may ship values outside this union). */
-export type RouteComplexity = 'trivial' | 'default' | 'complex' | 'deep'
-
-/**
- * Routing decision frame. Emitted once per turn as a LEADING frame
- * (between metadata and the `\x1E` end-of-leading-frames sentinel) when
- * the server's `decideRoute()` produces a `Route`.
- *
- * Field names use the `routed*` prefix on PURPOSE — the client's
- * catch-all leading-frame branch inspects `meta.model` / `meta.modelLabel`.
- * A bare `model` field on this frame would OVERWRITE the metadata frame's
- * modelLabel and break the <ModelDisplay> badge. The `routed` prefix
- * sidesteps that collision.
- *
- * Older clients that don't recognize `kind: 'routing'` silently drop
- * the frame (the catch-all only matches frames carrying known fields
- * like `sources` / `refs` / `modelLabel`).
- */
-export interface RoutingFrame {
-  kind: 'routing'
-  routedComplexity: RouteComplexity
-  routedModel: string
-  routedThinkingBudget: number
-}
-
-/**
- * Optional field on the trailing usage frame's `breakdown`. Surfaces
- * per-route attribution to the admin test console so an operator can
- * see "this turn ran on Haiku/trivial/$0.0005" without re-parsing the
- * stream. Additive: clients that ignore unknown keys keep working.
- */
-export interface RoutedAnswerBreakdown {
-  model: string
-  complexity: RouteComplexity
-  thinkingBudget: number
-}
-
-// =============================================================================
-// Leading frames
-// =============================================================================
-
-/** First frame on every stream — lets the shell render "Thinking…"
- *  within ~200ms, before any upstream byte arrives. */
-export interface StatusThinkingFrame {
-  status: 'thinking'
-}
-
-/** Per-turn metadata frame. The emitter sends `options.metadata`
- *  verbatim; a separate refs-only frame may follow with the same shape.
- *  All fields optional — the decoder's catch-all treats ANY frame that
- *  didn't match a `kind` discriminant as metadata-ish. */
-export interface ChatMetadataFrame {
-  /** Retrieval sources for the source-chip strip. Host-defined row
-   *  shape (`ChatSource` on the adapter side) — opaque at wire level. */
-  sources?: unknown[]
-  /** Per-row refs for inline object cards, keyed `<type>:<id>`. */
-  refs?: Record<string, unknown>
-  /** Raw model id (e.g. 'claude-sonnet-x'). Presence alone triggers the
-   *  client's meta merge; the value itself is not stored. */
-  model?: string
-  modelLabel?: string
-  provider?: string
-  contextWindowMaxTokens?: number
-  /** Per-message viewport-positioning hint ('top' | 'bottom'). */
-  scrollAnchor?: string
-}
-
-/** Live adaptive-thinking delta. WIRE IS ALREADY DELTA (Anthropic
- *  thinking_delta slices) — decoders must NOT diff or re-accumulate. */
-export interface ThinkingDeltaFrame {
-  kind: 'thinking-delta'
-  text: string
-}
-
-/** Usage frame emitted as a LEADING frame right after Anthropic's
- *  message_start (stage='start'). */
-export interface UsageStartFrame {
-  kind: 'usage'
-  stage: 'start'
-  input_tokens: number
-  cache_read_input_tokens?: number
-  cache_creation_input_tokens?: number
-}
-
-/** Model preamble prose written BEFORE a tool_use block — emitted as a
- *  standalone leading frame so it isn't stranded behind the approval
- *  card (the `\x1E` sentinel is suppressed on tool turns). */
-export interface TextLeadingFrame {
-  kind: 'text-leading'
-  text: string
-}
-
-/** Tool invocation failed server-side (proposal persist error,
- *  validation, ownership denial …). */
-export interface ToolErrorFrame {
-  kind: 'tool_error'
-  toolName?: string
-  toolUseId?: string
-  message: string
-}
-
-export interface ApprovalRequestField {
-  label: string
-  value: string
-}
-
-/** The model called a write tool; the server persisted a proposal and
- *  ships a card-ready payload. Shape mirrors the hub's `onToolUse`
- *  return in `lib/data/doc-chat-utils.ts`. */
-export interface ApprovalRequestFrame {
-  kind: 'approval_request'
-  proposalId: string
-  toolName: string
-  title?: string
-  fields?: ApprovalRequestField[]
-  preamble?: string | null
-  args?: Record<string, unknown>
-  expiresAt?: string
-  ttlSeconds?: number
-}
-
-/** Server-driven post-approve / post-reject frame (confirm-tool route).
- *  Mirror of the hub's `DecisionResolvedFrame` in
- *  `lib/data/chat-agent-utils.ts` (tool_name widened to string — the
- *  known-write-tool whitelist is host-side knowledge). */
-export interface DecisionResolvedFrame {
-  kind: 'decision_resolved'
-  /** The proposal this decision resolved — locates the SOURCE approval
-   *  card so the shell can flip its status + append the receipt. */
-  proposalId: string
-  ok: boolean
-  action: 'approved' | 'rejected'
-  tool_name?: string
-  result?: {
-    ticket_id?: string
-    status?: string | null
-    mirror_synced?: boolean
-  }
-  card?: {
-    type: string
-    marker: string
-    ref: unknown
-  }
-  /** True when the server WILL pipe an auto-continuation turn after
-   *  this frame. */
-  willAutoContinue: boolean
-  /** Pre-rendered receipt copy from the source strategy's
-   *  `receiptRenderer` — client renders verbatim. */
-  receiptText?: string
-}
-
-/** Every leading frame the emitter can produce. */
-export type SseLeadingFrame =
-  | StatusThinkingFrame
-  | ChatMetadataFrame
-  | RoutingFrame
-  | ThinkingDeltaFrame
-  | UsageStartFrame
-  | TextLeadingFrame
-  | ToolErrorFrame
-  | ApprovalRequestFrame
-  | DecisionResolvedFrame
-
-// =============================================================================
-// Trailing usage frame
-// =============================================================================
-
-/** Card/chip emission counts for admin adoption tooling. */
-export interface UsageTelemetry {
-  cards: number
-  chips: number
-  sentences: number
-  answerLen: number
-}
-
-/** Trailing usage frame — `\x1F` + JSON, runs to stream end (no
- *  terminator). `stage: 'display'` is a legacy alias the decoder treats
- *  identically to `'end'`. */
-export interface SseTrailingUsageFrame {
-  kind: 'usage'
-  stage: 'end' | 'display'
-  input_tokens?: number
-  output_tokens?: number
-  cache_read_input_tokens?: number
-  cache_creation_input_tokens?: number
-  hit_rate_pct?: number
-  telemetry?: UsageTelemetry
-  /** Cross-call usage breakdown (Haiku rewriter / classifier /
-   *  summarizer + routed-answer attribution). */
-  breakdown?: {
-    haikuRewriter?: { input: number; output: number }
-    haikuClassifier?: { input: number; output: number }
-    haikuSummarizer?: { input: number; output: number }
-    routedAnswer?: RoutedAnswerBreakdown
-  }
-  /** Gated deep-debug payload (only present when the request carried
-   *  the privileged debug secret). */
-  debug?: Record<string, unknown>
-}

package/src/chat-protocol/index.ts

@@ -1,21 +0,0 @@
-/**
- * Chat wire-protocol SSOT.
- *
- * The byte-level SSE framing contract (frames + encode + decode) and the
- * transport-agnostic `ChatStreamEvent` union both the SSE and NATS
- * decoders emit. Published as the server-safe `./chat-protocol` subpath —
- * no React, no browser APIs beyond TextEncoder/TextDecoder — so the hub's
- * stream route (emit side) and the lib's chat hooks (decode side) share
- * one protocol module.
- */
-
-export * from './frames'
-export * from './events'
-export * from './encode'
-export * from './decode'
-export * from './nats-decoder'
-// 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
-// forwarding above must be parsed IDENTICALLY on both sides of the seam.
-export * from './env-flag'