feat(server): unary HTTP steer + cancel-steer endpoints (ADR 0252) - #967
Open
jtenniswood wants to merge 1 commit into
Open
feat(server): unary HTTP steer + cancel-steer endpoints (ADR 0252)#967jtenniswood wants to merge 1 commit into
jtenniswood wants to merge 1 commit into
Conversation
POST /v1/sessions/{id}/steer enqueues text and/or multimodal parts (through
the existing toContentParts choke point) into the live run's steer inbox via
Service.Steer, with an optional strict expected_run_id (mismatch or a named
terminal run answers 409 stale_run_control); when no live run can take an
unqualified steer it promotes through the run-entry funnel and relays the
follow-up run as SSE on the same response, or background-drains into the
durable event log behind a {"outcome":"too_late","promoted":true} ack when
the writer cannot stream. POST /v1/sessions/{id}/cancel-steer retracts the
pending (un-drained) steer. The pair self-describes as http_steer in the
feature registry so clients feature-detect instead of sniffing.
Two deliberate departures from the feat/studio-atrium branch this is carved
from: Service.SteerEnqueue is deleted rather than carried (production-dead —
the handler calls Service.Steer; zero callers remained) with the
classification rationale corrected, and the never-shipped steer-cancel alias
is dropped (no released client called it; the tests now exercise the
canonical route, and the stale never-promotes package comment is corrected).
Docs in the same change per repo rule: the http-sse-api steer section,
api-surface rows (corrected to the registered cancel-steer naming),
IMPLEMENTATION-NOTES wire section, user-docs grpc-http, ADR 0252 flipped
Proposed→Accepted, llms.txt regenerated.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
jtenniswood
added
documentation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Stack 2/21 — HTTP steer + cancel-steer endpoints (ADR 0252)
The only daemon-side Go change in the whole #618 series — landing at the bottom of the stack so every remaining PR is pure TypeScript/config/docs. Independently valuable beyond Studio (#873, TS SDK #821).
What it adds (per ADR 0252, status flipped Proposed → Accepted here):
POST /v1/sessions/{id}/steer— unary steer into the live run's inbox via the sameService.Steerthe gRPC frame uses: text and/or multimodalpartsthrough the existingtoContentPartschoke point, optional strictexpected_run_id(mismatch/terminal →409 stale_run_control), promote-and-relay as SSE when no live run can take it (background-drain into the durable event log behind a{"outcome":"too_late","promoted":true}ack when the writer cannot stream).POST /v1/sessions/{id}/cancel-steer— retracts the pending (un-drained) steer (retracted/none_pending).features.goregistry rowhttp_steer— clients feature-detect instead of sniffing.Two deliberate deviations from the original branch, called out for review:
Service.SteerEnqueueis deleted, not carried. At the branch tip it was production-dead (the HTTP handler callsService.Steer; zero callers remained) — replaying it would land dead exported surface. The classification table'sSteerrationale is corrected accordingly.steer-canceldeprecated alias is dropped. No released client ever called it (Studio already uses the canonicalcancel-steer); the ~6 test sites that exercised the alias path now exercise the canonical route, and the stale never-promotes package comment onsteer_http_test.gois corrected to the promote-and-relay contract that actually shipped.Docs, same PR per repo rule:
docs/usage/http-sse-api.mdsteer section,docs/architecture/api-surface.mdrows (corrected from the branch'ssteer-cancelnaming drift to the registered routes), IMPLEMENTATION-NOTES steer wire section,user-docs/building/deployment/grpc-http.md,llms.txtregenerated.No
engine/orcontracts/changes — no api-compat or buf surface.task lint && task testgreen.🤖 Generated with Claude Code