feat(server): session-scoped elicitation sink for API/server runtimes (#3584) by aheritier · Pull Request #3625 · docker/docker-agent

aheritier · 2026-07-13T14:41:27Z

feat(server): session-scoped elicitation sink for API/server runtimes (#3584)

Summary

Lets elicitation (user-input) requests raised by API/server-created runtimes — including background jobs — reach a connected client, instead of being misclassified as headless and silently fast-declined. Part 4 (top) of the #3584 stack.

Stacked on the TUI/app PR — review the diff against that branch.

What changed

Session-scoped sink: runtimeForSession registers a per-session OnElicitationRequest sink that appends elicitation events to a lazily created session event log, replayable via GET /api/sessions/:id/events.
Event-log lifecycle: the lazy log is closed on session delete (single + batch), so a connected /events stream receives session_exited and terminates rather than blocking forever.
Docs: API-server docs updated for the /events out-of-band elicitation flow on API-created sessions, and the answer-vs-raise wording on the POST endpoint.

Testing

Session-scoped sink wiring; delete (single + batch) closes a live /events stream; server-side background elicitations surface instead of fast-declining.
Full stack task dev + -race — green.

Sayt-0 · 2026-07-16T08:44:57Z

@aheritier some commits are not signed can you check ?

Register a session-scoped elicitation sink on every API/server runtime so that background elicitations are routed to a lazily-created session event log rather than being fast-declined by the headless path (which fires when no sink is registered). Previously only the TUI registered an OnElicitationRequest sink, meaning every API-created runtime had none. The headless elicitation handler therefore declined all background elicitations immediately, even when a remote SSE client could have answered them via `POST .../elicitation`. The session-scoped event log is now created on demand the first time an out-of-band event is raised, making the session's `GET .../events` stream replayable without requiring an attached `--listen` runtime. Tests pin the lazy-creation behaviour and confirm that repeated sink invocations accumulate events rather than overwriting an existing event log. Documentation is updated to reflect that `GET .../events` is also available for any API-created session that has raised at least one out-of-band event. Closes: #3584

@dgageot

docker-agent 1.111.0 Created-by: HarmonybrewBot Commit-by: HarmonybrewBot Merged-by: HarmonybrewBot Description: Created by `brew bump` --- Created with `brew bump-formula-pr`.<details> <summary>release notes</summary> <pre>This release adds a new scheduler toolset, inline Mermaid diagram rendering, model switching in the lean TUI, project config autodiscovery, and a range of bug fixes and performance improvements across the agent, TUI, and server. ## What's New - Adds a built-in `scheduler` toolset with `create_schedule`, `list_schedules`, and `cancel_schedule` tools, enabling agents to schedule instructions to run once at a time, after a delay, or on a recurring interval - Adds prompt cache miss warnings via an opt-in `warn_on_cache_miss` user setting that emits notifications when cached input tokens are absent after the first session response - Adds inline Mermaid diagram rendering in the TUI - Adds model switching (`/model`) to the lean TUI and shares fuzzy model search between the lean and full TUIs - Adds autodiscovery of `docker-agent.yaml`, `docker-agent.yml`, and `docker-agent.hcl` project config files for no-argument local `docker agent run` - Surfaces background-job elicitation (user-input) requests in the TUI, ensuring each request opens exactly one dialog regardless of which runtime delivers it - Makes a custom `base_url` on a model automatically imply `bypass_models_gateway: true`, removing the need to set it explicitly ## Improvements - Improves session cost details in the TUI: aligns layout, color-codes cost percentages per message, groups averages together, and puts "Total" on its own line - Speeds up model switcher credential discovery by deduplicating credential names and resolving lookups concurrently, reducing model-picker latency - Parallelizes toolset startup and prefetches the MCP catalog off the load critical path, reducing agent startup time ## Bug Fixes - Fixes glob wildcard matching in permissions so `*` and `?` span path separators (`/`) in argument values such as file paths and URLs - Fixes a bug where setting `defer_all: true` on a toolset caused the toolset's custom `Instructions` to be permanently dropped from the agent's context - Fixes `SafetyPolicy` not persisting across turns, causing users to be re-prompted for tool approvals they had already opted into - Fixes background elicitations over the API so requests from concurrent background jobs are replayable and answerable instead of being auto-declined - Fixes Anthropic cache breakpoints exceeding the hard limit of 4 when deferred tools are present, which caused API errors at runtime - Fixes the TUI editor not regaining focus after external editing (`Ctrl+G`), which caused Enter to route to the transcript instead of sending the composed message - Fixes the scheduler schema so `type: scheduler` is accepted in agent config files (was previously rejected by JSON schema validation) - Fixes foreground elicitations being delivered twice into the app event stream - Fixes a mutex unlock in the scheduler's `setRuntime` method to use `defer` for safer lock release - Fixes VCR cassette path normalization for portable prompt-file matching - Fixes CI workflow YAML indentation that caused all CI runs to fail before any job could start ## Technical Changes - Adds `MapSlice` fan-out helper in the concurrent utilities package and uses it for parallel toolset operations - Serializes interactive OAuth flows across toolsets to prevent concurrent conflicts - Brings the documentation portal to WCAG 2.1 AA conformance across light and dark themes and adds a pa11y-ci CI gate to maintain it - Adds new documentation pages for the scheduler toolset, sandbox templates, custom commands, user settings, context and compaction guide, and fixes stale command syntax in the Named Commands docs --- ## What's Changed * docs: update CHANGELOG.md for v1.110.0 by @docker-read-write[bot] in docker/docker-agent#3665 * fix: repair CI workflow YAML and failing AgentsMd e2e test on main by @dgageot in docker/docker-agent#3666 * feat(tools): add "scheduler" toolset to run instructions on a time or recurring interval by @dwin-gharibi in docker/docker-agent#3632 * fix(config): add scheduler toolset to agent-schema.json type enum by @aheritier in docker/docker-agent#3670 * feat: custom base_url implies bypass_models_gateway by @dgageot in docker/docker-agent#3667 * feat: add prompt cache miss warnings by @rumpl in docker/docker-agent#3671 * Improve session cost details by @rumpl in docker/docker-agent#3672 * perf: speed up model switcher credential discovery by @rumpl in docker/docker-agent#3673 * Add model switching to the lean TUI by @rumpl in docker/docker-agent#3674 * feat(tui,app): surface & correlate background-job elicitations (#3584) by @aheritier in docker/docker-agent#3624 * chore: bump go-isatty, openai-go, and libopenapi by @dgageot in docker/docker-agent#3675 * ci: bump golangci-lint-action to v9.3.0 and fix DeferMutexUnlock lint offense by @dgageot in docker/docker-agent#3676 * ci: bump pinned actions to latest same-major versions by @dgageot in docker/docker-agent#3677 * feat(server): session-scoped elicitation sink for API/server runtimes (#3584) by @aheritier in docker/docker-agent#3625 * Render Mermaid diagrams inline by @rumpl in docker/docker-agent#3679 * fix(server): surface background elicitations over API by @Sayt-0 in docker/docker-agent#3678 * fix(teamloader): preserve deferred toolset instructions by @Piyush0049 in docker/docker-agent#3680 * fix(permissions): match glob wildcards across path separators by @parveshsaini in docker/docker-agent#3605 * docs(agents): fix stale command syntax and sub_agents claim in Named Commands by @aheritier in docker/docker-agent#3684 * docs(sandbox): document Docker Sandboxes integration and published sbx templates by @aheritier in docker/docker-agent#3682 * docs: surface orphan pages and add compaction, commands, and user-settings docs by @aheritier in docker/docker-agent#3683 * fix(docs): WCAG 2.1 AA accessibility remediation for the docs portal by @aheritier in docker/docker-agent#3687 * fix(tui): refocus the editor after external editing so Enter sends the content by @dgageot in docker/docker-agent#3690 * Implements the path-aware, two-tier documentation accessibility CI gate by @aheritier in docker/docker-agent#3691 * feat(run): autodiscover project agent config by @HajimohammadiNet in docker/docker-agent#3681 * perf: parallelize toolset startup and prefetch MCP catalog by @dgageot in docker/docker-agent#3688 * fix(anthropic): keep cache breakpoints within Anthropic's limit of 4 with deferred tools by @dgageot in docker/docker-agent#3692 * fix(docs): render --link-hover on light-mode callout-link hover by @aheritier in docker/docker-agent#3693 * build(deps): bump the pip group across 1 directory with 2 updates by @dependabot[bot] in docker/docker-agent#3697 * fix(session): persist SafetyPolicy across turns by @trungutt in docker/docker-agent#3685 ## New Contributors * @parveshsaini made their first contribution in docker/docker-agent#3605 * @HajimohammadiNet made their first contribution in docker/docker-agent#3681 **Full Changelog**: docker/docker-agent@v1.110.0...v1.111.0 </pre> <p>View the full release notes at <a href="https://github.com/docker/docker-agent/releases/tag/v1.111.0">https://github.com/docker/docker-agent/releases/tag/v1.111.0</a>.</p> </details> <hr> See merge request: Harmonybrew/homebrew-core!14465

aheritier mentioned this pull request Jul 13, 2026

fix(runtime): reliable, correlation-safe, non-blocking elicitation delivery (#3584) #3587

Merged

aheritier added area/api For features/issues/fixes related to the usage of the cagent API area/docs Documentation changes kind/feat PR adds a new feature (maps to feat:). Use on PRs only. labels Jul 13, 2026

aheritier force-pushed the feat/tui-background-elicitations branch from d2926c8 to 4b4ed27 Compare July 15, 2026 19:33

aheritier force-pushed the feat/server-session-elicitation-sink branch from 85124bc to 836e723 Compare July 15, 2026 19:33

aheritier requested a review from docker-agent July 15, 2026 19:51

aheritier force-pushed the feat/server-session-elicitation-sink branch from 836e723 to 3c7d997 Compare July 15, 2026 20:32

aheritier force-pushed the feat/tui-background-elicitations branch from af5ba07 to f445d3e Compare July 15, 2026 20:47

aheritier force-pushed the feat/server-session-elicitation-sink branch from 3c7d997 to a91131a Compare July 15, 2026 20:47

Base automatically changed from feat/tui-background-elicitations to main July 16, 2026 06:34

aheritier force-pushed the feat/server-session-elicitation-sink branch from a91131a to 53f2f40 Compare July 16, 2026 08:05

aheritier marked this pull request as ready for review July 16, 2026 08:07

aheritier requested a review from a team as a code owner July 16, 2026 08:07

melmennaoui approved these changes Jul 16, 2026

View reviewed changes

Sayt-0 approved these changes Jul 16, 2026

View reviewed changes

dgageot approved these changes Jul 16, 2026

View reviewed changes

aheritier force-pushed the feat/server-session-elicitation-sink branch from 53f2f40 to affcf18 Compare July 16, 2026 10:04

aheritier force-pushed the feat/server-session-elicitation-sink branch from affcf18 to 6a685c8 Compare July 16, 2026 10:05

Sayt-0 mentioned this pull request Jul 16, 2026

fix(server): surface background elicitations over API #3678

Merged

Sayt-0 merged commit 8aef68f into main Jul 16, 2026
17 checks passed

Sayt-0 deleted the feat/server-session-elicitation-sink branch July 16, 2026 10:11

BrewTestBot mentioned this pull request Jul 17, 2026

docker-agent 1.111.0 Homebrew/homebrew-core#293687

Merged

Navigation Menu

Repository navigation

feat(server): session-scoped elicitation sink for API/server runtimes (#3584) - #3625

feat(server): session-scoped elicitation sink for API/server runtimes (#3584)#3625
Sayt-0 merged 1 commit into
mainfrom
feat/server-session-elicitation-sink

aheritier commented Jul 13, 2026

Uh oh!

Sayt-0 commented Jul 16, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

aheritier commented Jul 13, 2026

Summary

What changed

Testing

Uh oh!

Sayt-0 commented Jul 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Sayt-0 commented Jul 16, 2026 •

edited

Loading