Skip to content

Commit df94fdc

Browse files
committed
docs(structure): record where a Chat instruction lands on the translated bridge
The inbound compatibility doc described the native Chat passthrough and the wire-side placement contract, but said nothing about which of the two homes a system or developer message reaches on the translated bridge. State it: a leading block is the request's instructions, a later one is a chronological developer item, and an instruction inside a tool batch waits for the batch to drain. The wire slot and the role it carries stay owned by the chronological in-conversation instructions contract, which this doc already links.
1 parent 6fc6fa7 commit df94fdc

1 file changed

Lines changed: 15 additions & 0 deletions

File tree

‎structure/data-planes/inbound-compat.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -110,6 +110,21 @@ or storage semantics retain the existing Chat -> Responses -> Chat bridge.
110110
Chat-to-Responses traffic that lands on `api.meta.ai` inherits the same 64-character tool-name
111111
aliasing as native Responses; see [`responses.md`](../transports/responses.md).
112112

113+
On that bridge, `src/chat/inbound.ts` decides where a `system` or `developer` message lands by
114+
where the caller wrote it. A leading block, before any conversational item exists, becomes
115+
`instructions`. One that arrives after the conversation has started becomes a chronological
116+
`role:"developer"` input item instead, the same representation `src/claude/inbound.ts` mints for a
117+
mid-conversation instruction, so the slot the caller chose survives to the adapter that preserves
118+
it. The role is `developer` rather than `system` because the native ChatGPT backend refuses a
119+
`system` item inside `input` and canonical forwarding folds a message-shaped `system` item back
120+
onto `instructions`. An instruction that arrives between a tool call and its result is held until
121+
the batch drains, or until the next user or assistant turn, so the pair the Kiro, Anthropic and
122+
Google mappers require to stay adjacent is never split. Placement on the wire is then owned by
123+
[chronological in-conversation instructions](../providers/chat-compat.md#chronological-in-conversation-instructions),
124+
which also decides which role that slot carries. Regression coverage is in
125+
`tests/responses/chat-inbound-developer-position.test.ts`, which compares the final upstream body
126+
on the native Chat route, a combo route and the Responses endpoint.
127+
113128
The direct SSE relay accepts CRLF and arbitrary transport chunk boundaries while retaining at most
114129
one bounded event. EOF with an unterminated event and an event above the translator limit are typed
115130
upstream failures, never successful partial completions. Provider-controlled structured error

0 commit comments

Comments
 (0)