Skip to content

Expose stable runtime turn IDs to built-in plugins #5487

Backlog

Description

@jdneo

Describe the feature or problem you'd like to solve

No response

Proposed solution

Problem

Browser Use needs an exact host-owned turn identity to return claimed User Tabs when the owning turn ends.

The current built-in integration exposes turn identity asymmetrically:

  • The Copilot SDK copies _meta["com.github.copilot/turnId"] onto MCP tools/call requests only when the SDK caller explicitly supplies the optional clientTurnId.
  • Built-in Copilot CLI and Copilot App sessions can therefore issue Browser MCP calls without an exact turn ID.
  • AgentStopHandler receives invocation: { sessionId }, but no turn ID that can be correlated with the MCP calls from the turn that stopped.

A session ID plus a timestamp is not enough to identify a turn reliably when hooks are delayed or reordered. Without a shared runtime turn ID, a built-in plugin must either keep User Tab ownership session-scoped, wait for idle recovery, or synthesize turn generations using cross-process state and locking.

Related Browser integration work: #397 and #398.

Request

Have the Copilot SDK/runtime and Copilot CLI expose a stable opaque turn ID to built-in plugins for every turn that can issue MCP calls, including turns started without a caller-provided clientTurnId.

The same runtime-owned ID should be available at both lifecycle surfaces:

  1. MCP tool invocation:
    • on the preMcpToolCall input and/or final tools/call.params._meta;
    • preferably through the existing _meta["com.github.copilot/turnId"] key when compatible, or through another documented host-owned key.
  2. Turn completion:
    • on the matching agentStop input or invocation context.

The important contract is that the ID observed on agentStop is exactly the ID used by MCP calls from the turn that stopped, rather than whichever turn is current when the hook is delivered.

Expected behavior

  • Every applicable turn has a nonempty, bounded, opaque host-owned ID, even when the SDK caller omits clientTurnId.
  • Multiple MCP calls in one turn receive the same ID.
  • A later distinct turn receives a different ID.
  • agentStop carries the ID of the turn that emitted the stop event.
  • A delayed Stop for turn A cannot be mistaken for turn B after turn B starts.
  • Existing caller-provided clientTurnId behavior remains compatible.
  • Parent, subagent, steering, Autopilot continuation, abort, and resume semantics are documented so plugins know which completion event matches each ID.
  • The metadata remains host-authored and outside model-visible tool arguments.

Browser Use outcome

With this contract, Browser Use can directly perform:

MCP tools/call(sessionId, turnId)
...
agentStop(sessionId, turnId)
→ cancel/drain that turn's Browser work
→ return only the User Tabs claimed by that turn

This removes the need for Browser-specific generated turn IDs, timestamp-to-turn lookup, cross-process lifecycle locks, and replay/cleanup bookkeeping while preserving precise per-turn User Tab reclamation.

Acceptance criteria

  • SDK and built-in CLI integration tests cover a turn with no caller-supplied clientTurnId and assert that its MCP calls and agentStop receive the same runtime turn ID.
  • Tests cover multiple MCP calls in one turn, two sequential turns, and a delayed Stop from the earlier turn.
  • Tests cover caller-supplied clientTurnId compatibility.
  • The public SDK hook types document and expose the Stop-side turn ID.

Example prompts or workflows

No response

Additional context

No response

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions