helexa/helexa
1
0
Fork 0
Code Issues 102 Pull Requests Actions Packages Projects Releases Wiki Activity

Responses API: emit response.in_progress and built-in-tool event families #7

New Issue
Open
opened 2026-05-31 08:19:37 +00:00 by grenade · 2 comments
grenade commented 2026-05-31 08:19:37 +00:00
Owner
Copy Link

Scope cut from Step 2 (commit 957f704)

The Responses projector emits a tight 8-event sequence:

response.created → response.output_item.added → response.content_part.added → response.output_text.delta × N → response.output_text.done → response.content_part.done → response.output_item.done → response.completed

That's enough for a Responses client to recover the assistant text. Out-of-scope today:

  1. response.in_progress — OpenAI emits this between response.created and the first content delta to signal "we're past prompt validation, model is generating". Some clients render a different spinner state based on it.
  2. Built-in tool event families — response.web_search_call.*, response.code_interpreter_call.*, response.file_search_call.*, response.image_generation_call.*. These exist for OpenAI's hosted tools; neuron doesn't have any of those tools wired up, so the events would never fire — but the clients that look for them will today render an error or fall back to chat-completions semantics.
  3. Reasoning event family — tracked separately in #5.
  4. Function-call event family — tracked separately in #6.

See crates/cortex-core/src/responses.rs::events for the constants module, and crates/neuron/src/wire/openai_responses.rs::emit_start_frames / emit_finish_frames for the emission sites.

Why it was cut

Most of these events carry no information the consumer doesn't already get from the surrounding events. in_progress is a marker, not a payload; the built-in-tool families are no-ops without the underlying tools. The minimum useful set was what mattered for Stage 6 of helexa-acp to start exercising the route.

What implementation looks like

response.in_progress

  1. Add the constant: pub const IN_PROGRESS: &str = "response.in_progress"; to cortex_core::responses::events.
  2. Emit between response.created and the first output_item event in emit_start_frames. Payload mirrors response.created — the shell with status: "in_progress".
  3. Test: extend full_stream_emits_expected_event_sequence to assert it's present.

That one is trivial. The next two depend on tool wiring that doesn't exist:

Hosted-tool families

Don't emit anything until we have the tools themselves. When we do (e.g. a web_search tool that proxies to an external search engine):

  1. Extend InferenceEvent with ToolInvocation { tool_id, name, status, … } variants.
  2. The hosted-tool implementation produces these events alongside TextDeltas.
  3. The Responses projector translates ToolInvocation events to the appropriate response.<tool>_call.* family.

This is the natural extension once tool wiring lands. No work to do until then.

Acceptance

  • response.in_progress lands cleanly with a test.
  • The hosted-tool event families are documented as deferred until the corresponding tools exist; this issue tracks the schema work, not the tool implementation.

Tracking

Cosmetic for in_progress (some clients are fussier than others). Hosted-tool families are blocked on actually having hosted tools; not relevant for neuron's current scope.

## Scope cut from Step 2 (commit [`957f704`](https://git.lair.cafe/helexa/cortex/commit/957f704)) The Responses projector emits a tight 8-event sequence: `response.created` → `response.output_item.added` → `response.content_part.added` → `response.output_text.delta` × N → `response.output_text.done` → `response.content_part.done` → `response.output_item.done` → `response.completed` That's enough for a Responses client to recover the assistant text. Out-of-scope today: 1. **`response.in_progress`** — OpenAI emits this between `response.created` and the first content delta to signal "we're past prompt validation, model is generating". Some clients render a different spinner state based on it. 2. **Built-in tool event families** — `response.web_search_call.*`, `response.code_interpreter_call.*`, `response.file_search_call.*`, `response.image_generation_call.*`. These exist for OpenAI's hosted tools; neuron doesn't have any of those tools wired up, so the events would never fire — but the clients that look for them will today render an error or fall back to chat-completions semantics. 3. **Reasoning event family** — tracked separately in #5. 4. **Function-call event family** — tracked separately in #6. See `crates/cortex-core/src/responses.rs::events` for the constants module, and `crates/neuron/src/wire/openai_responses.rs::emit_start_frames` / `emit_finish_frames` for the emission sites. ## Why it was cut Most of these events carry no information the consumer doesn't already get from the surrounding events. `in_progress` is a marker, not a payload; the built-in-tool families are no-ops without the underlying tools. The minimum useful set was what mattered for Stage 6 of helexa-acp to start exercising the route. ## What implementation looks like ### `response.in_progress` 1. Add the constant: `pub const IN_PROGRESS: &str = "response.in_progress";` to `cortex_core::responses::events`. 2. Emit between `response.created` and the first output_item event in `emit_start_frames`. Payload mirrors `response.created` — the shell with `status: "in_progress"`. 3. Test: extend `full_stream_emits_expected_event_sequence` to assert it's present. That one is trivial. The next two depend on tool wiring that doesn't exist: ### Hosted-tool families Don't emit anything until we have the tools themselves. When we do (e.g. a `web_search` tool that proxies to an external search engine): 1. Extend `InferenceEvent` with `ToolInvocation { tool_id, name, status, … }` variants. 2. The hosted-tool implementation produces these events alongside `TextDelta`s. 3. The Responses projector translates `ToolInvocation` events to the appropriate `response.<tool>_call.*` family. This is the natural extension once tool wiring lands. No work to do until then. ## Acceptance - `response.in_progress` lands cleanly with a test. - The hosted-tool event families are documented as deferred until the corresponding tools exist; this issue tracks the schema work, not the tool implementation. ## Tracking Cosmetic for in_progress (some clients are fussier than others). Hosted-tool families are blocked on actually having hosted tools; not relevant for neuron's current scope.
grenade commented 2026-06-12 08:58:14 +00:00
Author
Owner
Copy Link

Scope-narrowing note (2026-06-12 positioning): split this issue's three parts. (1) response.in_progress — worth emitting; cheap, real clients key spinner state off it; part of the same contract-completeness work as #24. (2) Built-in-tool event families (web_search_call.*, code_interpreter_call.*, …) — out of scope: those are hosted-platform tools helexa deliberately does not have, and emitting their event shapes without the backing tools would be fake compatibility. Clients that need hosted tools need a cloud provider, and that is fine. (3) Reasoning / function-call families stay tracked in their own issues. Suggest retitling to just the response.in_progress deliverable when picked up.

Scope-narrowing note (2026-06-12 positioning): split this issue's three parts. (1) `response.in_progress` — worth emitting; cheap, real clients key spinner state off it; part of the same contract-completeness work as #24. (2) Built-in-tool event families (`web_search_call.*`, `code_interpreter_call.*`, …) — out of scope: those are hosted-platform tools helexa deliberately does not have, and emitting their event shapes without the backing tools would be fake compatibility. Clients that need hosted tools need a cloud provider, and that is fine. (3) Reasoning / function-call families stay tracked in their own issues. Suggest retitling to just the `response.in_progress` deliverable when picked up.
grenade added the p3-later label 2026-06-12 09:01:46 +00:00
grenade commented 2026-06-20 08:57:34 +00:00
Author
Owner
Copy Link

Triage: the response.in_progress half of this issue is already implemented and tested on main — it was landed in a prior commit but the issue wasn't updated.

  • Constant: cortex_core::responses::events::IN_PROGRESS (crates/cortex-core/src/responses.rs:243).
  • Emission: emit_start_frames (crates/neuron/src/wire/openai_responses.rs:358-361) emits it immediately after response.created, carrying the same in_progress shell, with a comment explaining the created/in_progress pairing.
  • Test: full_stream_emits_expected_event_sequence asserts the full ordered sequence including events::IN_PROGRESS at position 2 (openai_responses.rs:820). Verified green just now.

So acceptance item 1 ("response.in_progress lands cleanly with a test") is met.

The remaining scope is the hosted-tool event families (response.web_search_call.*, code_interpreter_call.*, file_search_call.*, image_generation_call.*), which — per this issue's own writeup — are no-ops until the underlying hosted tools exist in neuron (none are wired). There's nothing to emit until that tool wiring lands. The InferenceEvent::ToolCall projector arm already carries a // Future work tracked in #7 breadcrumb for it.

Recommend narrowing this issue to just the deferred hosted-tool families (or closing and re-filing when tool wiring is on the roadmap), since the in_progress deliverable is done. Leaving it open and scoped to the tool-families for now.

Triage: the **`response.in_progress`** half of this issue is already implemented and tested on `main` — it was landed in a prior commit but the issue wasn't updated. - Constant: `cortex_core::responses::events::IN_PROGRESS` (`crates/cortex-core/src/responses.rs:243`). - Emission: `emit_start_frames` (`crates/neuron/src/wire/openai_responses.rs:358-361`) emits it immediately after `response.created`, carrying the same `in_progress` shell, with a comment explaining the created/in_progress pairing. - Test: `full_stream_emits_expected_event_sequence` asserts the full ordered sequence including `events::IN_PROGRESS` at position 2 (`openai_responses.rs:820`). Verified green just now. So acceptance item 1 ("`response.in_progress` lands cleanly with a test") is **met**. The remaining scope is the **hosted-tool event families** (`response.web_search_call.*`, `code_interpreter_call.*`, `file_search_call.*`, `image_generation_call.*`), which — per this issue's own writeup — are no-ops until the underlying hosted tools exist in neuron (none are wired). There's nothing to emit until that tool wiring lands. The `InferenceEvent::ToolCall` projector arm already carries a `// Future work tracked in #7` breadcrumb for it. Recommend **narrowing this issue to just the deferred hosted-tool families** (or closing and re-filing when tool wiring is on the roadmap), since the in_progress deliverable is done. Leaving it open and scoped to the tool-families for now.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
out-of-scope
Outside helexa's constraining principles: near-frontier models on consumer hardware, served transparently and predictably
 p1-now
Active pain or unblocking work — pick up first
 p2-next
Engine levers — start once P1 baselines exist
 p3-later
Dependent on earlier work, or demand-driven
No Label p3-later
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
grenade
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: helexa/helexa#7
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?