npm - @jsonstudio/rcc - Versions diffs - 0.89.1205 → 0.89.1457 - Mend

@jsonstudio/rcc 0.89.1205 → 0.89.1457

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (391) hide show

package/docs/streaming-flow.html ADDED Viewed

@@ -0,0 +1,30 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>/v1/messages Streaming Flow</title>
+    <script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
+    <script>mermaid.initialize({ startOnLoad: true, theme: 'default' });</script>
+    <style>
+      body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; margin: 24px; }
+      pre { background: #f5f5f5; padding: 16px; overflow: auto; }
+    </style>
+  </head>
+  <body>
+    <h1>/v1/messages Streaming Pipeline</h1>
+    <pre class="mermaid">
+flowchart TD
+    A["Client Request\n(JSON or SSE body)\nfields: messages/tools/tool_choice/stream"] --> B
+    B["HTTP Handler\nsrc/server/handlers/messages-handler.ts\nstream := body.stream\nmetadata.stream/inbound/outbound := stream"] --> C
+    C["req_inbound_stage1/2\nChatEnvelope parameters.stream := stream\ncollect tools/tool_outputs/tool_choice"] --> D
+    D["req_process_stage1_tool_governance\nTool filters adjust tool list/tool_choice\nstream untouched"] --> E
+    E["req_outbound_stage1/2\nBuild provider payload\npayload.stream := override(supportsStreaming) or stream"] --> F
+    F["Provider Upstream\nSSE or JSON depending on payload.stream\nreturns SSE/JSON with tool_calls & finish_reason"] --> G
+    G["resp_inbound stages\nDecode SSE, map to Chat response\ncapture tool_calls/tool outputs"] --> H
+    H["resp_process stages\nTool governance validation\nBuild final Chat response"] --> I
+    I["resp_outbound_stage1\nMap Chat response to client protocol\n(Anthropic/OpenAI/Responses)"] --> J
+    J["resp_outbound_stage2\nif metadata.stream == true -> emit SSE\nelse -> JSON"] --> K
+    K["HTTP Response\nsendPipelineResponse\nforceSSE := metadata.stream"]
+    </pre>
+  </body>
+</html>

package/docs/streaming-flow.md ADDED Viewed

@@ -0,0 +1,182 @@
+## `/v1/messages` Streaming/Tool Flow
+### HTTP Entry → `req_inbound` Stages
+| Stage | Payload focus | Key fields |
+|-------|---------------|------------|
+| HTTP handler (`src/server/handlers/messages-handler.ts`) | Raw JSON/SSE body | `jsonPayload.stream`, `rawRequestMetadata`, `metadata.stream/inboundStream/outboundStream`, `clientHeaders` |
+| `req_inbound_stage1_format_parse` | Format envelope | Mirrors request body (Anthropic/Chat/Responses → canonical format) |
+| `req_inbound_stage2_semantic_map` | `ChatEnvelope` + `StandardizedRequest` | `parameters.stream`, `messages`, `tools`, `metadata.context` |
+| `req_inbound_stage3_context_capture` | Adapter context | Captures protocol-specific hints, `toolCallIdStyle`, alias maps |
+**Flow**
+1. Client body `stream` is taken as ground truth. Handler copies it into `jsonPayload.stream` and marks `metadata.stream/inboundStream/outboundStream`.
+2. Format adapter normalises body into Chat envelope (Anthropic messages → canonical chat).
+3. Semantic mapper builds `ChatEnvelope`, collecting `tools`, `tool_outputs`, `tool_choice`, `parameters.stream`.
+4. `ChatEnvelope → StandardizedRequest` copies `parameters.stream`, `messages`, `tools`, metadata.
+### Request Process (`req_process_stage1_tool_governance`)
+* Input: `StandardizedRequest` with `parameters.stream` from client.
+* Tool filters (`runChatRequestToolFilters`) govern tool list/tool choice without touching `stream`.
+* `ProcessedRequest.processingMetadata.toolCalls` records governed tool call plan.
+### Request Outbound (`req_outbound_stage*`)
+| Stage | Effect |
+|-------|--------|
+| `req_outbound_stage1_semantic_map` | Reconstruct ChatEnvelope for provider protocol (`AdapterContext.providerProtocol`). |
+| `req_outbound_stage2_format_build` | Produce provider payload, map `tools` & `tool_choice`. Apply provider `supportsStreaming` override. |
+**Streaming rule**
+```
+if provider.profile.supportsStreaming === true  => payload.stream = true
+if provider.profile.supportsStreaming === false => payload.stream = false
+else                                           => payload.stream = StandardizedRequest.parameters.stream
+```
+### Provider Layer
+* Request uses final `payload.stream`.
+* Response can be SSE or JSON. Driver normalises it to JSON before handing to Hub.
+### Response Inbound
+| Stage | Effect |
+|-------|--------|
+| `resp_inbound_stage1_sse_decode` | Decode SSE if provider returned stream. |
+| `resp_inbound_stage2_format_parse` | Map provider payload to format envelope. |
+| `resp_inbound_stage3_semantic_map` | Build Chat response (tool_calls, tool outputs, finish reason). |
+### Response Process
+| Stage | Effect |
+|-------|--------|
+| `resp_process_stage1_tool_governance` | Validates provider tool calls (IDs, schema, arguments). |
+| `resp_process_stage2_finalize` | Builds final Chat response JSON (`choices`, `usage`, `finish_reason`). |
+### Response Outbound
+| Stage | Effect |
+|-------|--------|
+| `resp_outbound_stage1_client_remap` | Convert final Chat response into client protocol (`Anthropic Messages`, `OpenAI Chat`, `Responses`). |
+| `resp_outbound_stage2_sse_stream` | Emits SSE iff `metadata.stream === true` (entrance value). Otherwise returns JSON. |
+**Important**: Outbound streaming decision ignores provider response type; it only checks client entrance metadata.
+---
+## Stage Reference (request → response)
+| Pipeline section | Stages |
+|------------------|--------|
+| Request inbound  | `req_inbound_stage1_format_parse`, `req_inbound_stage2_semantic_map`, `req_inbound_stage3_context_capture` |
+| Request process  | `req_process_stage1_tool_governance`, `req_process_stage2_route_select` |
+| Request outbound | `req_outbound_stage1_semantic_map`, `req_outbound_stage2_format_build` |
+| Response inbound | `resp_inbound_stage1_sse_decode`, `resp_inbound_stage2_format_parse`, `resp_inbound_stage3_semantic_map` |
+| Response process | `resp_process_stage1_tool_governance`, `resp_process_stage2_finalize` |
+| Response outbound| `resp_outbound_stage1_client_remap`, `resp_outbound_stage2_sse_stream` |
+SSE/JSON selection happens at `resp_outbound_stage2_sse_stream` based solely on `metadata.stream`.
+### HTTP Response
+`sendPipelineResponse` uses `options.forceSSE = metadata.stream`. SSE events follow client protocol (Anthropic `message_start/content_block_delta`, OpenAI `chat.completion.chunk`, etc.). JSON includes canonical `choices/tool_calls/tool_outputs/finish_reason`.
+---
+## Field / Stage State Summary
+| Field | HTTP handler | req_inbound | req_process | req_outbound | provider resp | resp_inbound | resp_process | resp_outbound |
+|-------|--------------|-------------|-------------|--------------|---------------|--------------|--------------|---------------|
+| `stream` | Set from client body | Copied to `parameters.stream` | Unchanged | Override only if provider config forces | n/a | Remains in metadata | Drives `wantsStream` | Controls SSE vs JSON |
+| `tools` | Raw array | Normalised Chat tools | Tool governance (policy) | Mapped to provider schema | Provider call result | Normalised Chat tool calls | Validated/strictified | Mapped back to client schema |
+| `tool_choice` | Raw | Stored in parameters | Governed | Provider schema | — | — | Included in final Chat response | Client schema |
+| `tool outputs` | Raw (Responses) | Stored as `toolOutputs` | — | Provider payload (if needed) | Provider result frames | Normalised to Chat tool role msg | Packaged | Client schema (Messages, Responses) |
+| `finish_reason` | — | — | — | Provider dependent | Provided by provider | Normalised to Chat finish reason | Finalised | Returned in client schema |
+---
+## Protocol-specific Conversion Details
+### OpenAI Chat (`/v1/chat/completions`)
+**Inbound**
+1. `req_inbound_stage1_format_parse` accepts OpenAI Chat JSON.
+2. `req_inbound_stage2_semantic_map` flattens `choices[].messages` into ChatEnvelope, collects `tool_calls`, `tool_choice`.
+3. `req_inbound_stage3_context_capture` stores `toolCallIdStyle` hints.
+**Outbound**
+1. `req_outbound_stage1_semantic_map` reconstructs OpenAI Chat payload with governed `tools`.
+2. `req_outbound_stage2_format_build` serialises `function` schema, `tool_choice`, `stream`.
+3. `resp_outbound_stage1_client_remap` writes `choices[].delta`, `finish_reason`, `tool_calls`.
+4. `resp_outbound_stage2_sse_stream` emits `chat.completion.chunk` events when `stream === true`.
+### Anthropic Messages (`/v1/messages`)
+**Inbound**
+1. `req_inbound_stage1_format_parse` parses Anthropic `messages[]/content_block` structure.
+2. `req_inbound_stage2_semantic_map` converts to ChatEnvelope, capturing `anthropicMirror`, alias map, metadata.
+3. `req_inbound_stage3_context_capture` stores Anthropics-specific aliasing + tool ID style.
+**Outbound**
+1. `req_outbound_stage1_semantic_map` builds Anthropics message list (system blocks, tool_use, tool_result).
+2. `req_outbound_stage2_format_build` sets `tools`, `tool_choice`, `stream` (respecting provider override).
+3. Provider response SSE → `resp_inbound_stage1_sse_decode`.
+4. `resp_outbound_stage1_client_remap` emits `message_start`, `content_block_start/delta`, tool_use/tool_result, `message_delta.stop_reason`.
+5. `resp_outbound_stage2_sse_stream` uses entrance `stream` to send SSE; otherwise JSON matches Anthropic schema.
+### OpenAI Responses (`/v1/responses`)
+**Inbound**
+1. Handler routes `/v1/responses` to `responses-format-adapter`.
+2. `req_inbound_stage2_semantic_map` maps `input[]` into ChatEnvelope (`messages/tools`), `tool_outputs`.
+3. `req_inbound_stage3_context_capture` records responses context for bridging (multi-modal).
+**Outbound**
+1. `req_outbound_stage1_semantic_map` converts ChatEnvelope to Responses `input[]`.
+2. `req_outbound_stage2_format_build` writes `metadata`, `modalities`, `instructions`, `stream`.
+3. Provider SSE or JSON feeds `resp_inbound_*`; tool outputs appear as `response.output[]`.
+4. `resp_outbound_stage1_client_remap` rebuilds Responses `output[]` array (tool calls, tool results, reasoning, finish status).
+5. `resp_outbound_stage2_sse_stream` emits Responses SSE events when entrance `stream === true`.
+---
+---
+## Streaming / Tool Pipeline Flow
+```
+Client (/v1/messages)
+  → HTTP handler
+      stream := body.stream
+      metadata.stream/inbound/outbound := stream
+  → req_inbound_stage1 (format parse)
+  → req_inbound_stage2 (semantic map)
+      ChatEnvelope.parameters.stream := stream
+  → StandardizedRequest.parameters.stream := stream
+  → req_process_stage1_tool_governance
+      tools/tool_choice governed (stream untouched)
+  → req_outbound_stage1/2
+      apply provider supportsStreaming override
+      payload.stream := override or stream
+  → Provider
+      sends SSE/JSON accordingly
+      returns SSE/JSON (tool_calls, finish_reason)
+  → resp_inbound stages
+      decode SSE, build Chat response
+  → resp_process
+      tool governance, final Chat response
+  → resp_outbound_stage1
+      map Chat response -> client protocol
+  → resp_outbound_stage2
+      if entrance stream === true -> emit client SSE
+      else -> emit JSON
+  → HTTP response
+```
+---
+See `streaming-flow.html` for a Mermaid diagram illustrating the above.