feat: Add session control endpoints to public API#855
Open
tiwillia wants to merge 8 commits intoambient-code:mainfrom
Open
feat: Add session control endpoints to public API#855tiwillia wants to merge 8 commits intoambient-code:mainfrom
tiwillia wants to merge 8 commits intoambient-code:mainfrom
Conversation
…ndpoints Captures the planned v1 API surface including session CRUD, messaging, output retrieval, runs, start/stop, and interrupt.
…, and lifecycle Add 7 new endpoints to the public API gateway: - POST /sessions/:id/runs — create an AG-UI run with full control - GET /sessions/:id/runs — list run summaries derived from export events - POST /sessions/:id/message — simplified message sending (auto-generates run/message IDs) - GET /sessions/:id/output — retrieve session output in transcript, compact, or events format - POST /sessions/:id/start — resume a stopped/completed session (422 if already running) - POST /sessions/:id/stop — stop a running session (422 if already completed/failed) - POST /sessions/:id/interrupt — send interrupt signal to cancel current run Key implementation details: - Uses backend export endpoint to fetch AG-UI events (no SSE parsing needed) - Derives run summaries by grouping events by runId - Transcript format extracts assembled messages from MESSAGES_SNAPSHOT events - Compact format merges consecutive TEXT_MESSAGE_CONTENT/TOOL_CALL_ARGS deltas - Lifecycle endpoints check session phase before acting to prevent invalid transitions - Adds DisplayName and Repos fields to SessionResponse - Promotes github.com/google/uuid from indirect to direct dependency
- Filter forwarded errors to only expose the "error" field, preventing internal detail leakage (namespaces, K8s traces) - Add phase guards to lifecycle and messaging endpoints (defense-in-depth) - Standardize JSON casing: snake_case in public API, camelCase to backend - Lowercase unknown phases in normalizePhase to maintain API contract - Validate run_id as UUID, format as enum, session IDs as K8s names - Stable sort for run summaries by insertion order
- Fix JSON casing: createdAt/completedAt → created_at/completed_at - Add 422 responses to POST /message and POST /runs (session not running) - Add 409 responses to POST /start and POST /stop (unknown phase) - Remove phantom 422 from POST /interrupt (no phase guard in code) - Fix start/stop descriptions referencing wrong status code (409 → 422) - Remove unused message field from ErrorResponse schema
Add display_name to CreateSessionRequest DTO and forward it as displayName (camelCase) to the backend. Update OpenAPI spec to document the field.
tiwillia
force-pushed
the
feat/public-api-session-control
branch
from
7db465f to
6f332f8
Compare
…ext canceled errors ProxyRequest deferred context cancellation before returning the response, causing callers to get "context canceled" when reading large response bodies (e.g. list sessions). Small responses worked by chance because the body was already buffered in the transport layer. Return the cancel function to callers so cancellation happens after the response body has been read. All callers and tests updated accordingly.
- Send "initialPrompt" instead of "prompt" (backend field name)
- Send flat repo objects {url, branch} instead of nested {input: {url, branch}}
- Read "initialPrompt" first in transformSession, falling back to "prompt"
- Update tests accordingly
…session creation The public API gateway was silently dropping activeWorkflow and environmentVariables fields from POST /v1/sessions requests. Add these fields to CreateSessionRequest DTO, forward them in the backend request transformation, and update the OpenAPI spec.
5 tasks
Contributor
🚦 Review Queue StatusThis PR has 1 blocker(s) preventing merge:
Action NeededResolve line overlap with PR #755 (may be a false positive or require coordination), then ready for review This comment is posted by the Review Queue workflow. It will update when blockers change. |
Open
4 tasks
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.
Enhances the public API to enable session control.
Prior to this change, the public API is limited to supporting CRUD on sessions. This lacked any ability to control and review session output. The following APIs are added as part of this change:
POST/sessions/{id}/messageSendMessageRequest202GET/sessions/{id}/output200POST/sessions/{id}/runsCreateRunRequest202GET/sessions/{id}/runs200POST/sessions/{id}/start202POST/sessions/{id}/stop202POST/sessions/{id}/interrupt200These endpoints make it possible to orchestrate sessions using the public API. This can enable external tools to automate session orchestration and, with RBAC changes, could enable session agents to interact with other sessions through gathering output and sending messages.
This change also contains several fixes against the existing session CRUD endpoints, including:
display_namesupportNote that the public API is currently unused by any existing client, UI, etc - but is proposed to be the primary way clients interact with the platform. This change assumes that is still the current intent, as all of this functionality is already available in the backend API.