Allow Canvas extensions to open or focus an existing local session

[jdneo]

Feature summary

Expose a capability-gated App host API that allows a Canvas extension to open or focus an existing local runtime session in Chat View.

What problem are you trying to solve?

I am building a Canvas extension that visualizes a tree of forked local Copilot sessions.

After calling sessions.fork, the extension receives the child runtime session ID. The Canvas needs to support two workflows:

1. Automatically enter the newly created child session.
2. Let the user select an existing branch and click Open Chat.

There is currently no supported way to switch the Copilot App Chat View to that runtime session.

The available alternatives do not provide this behavior:

• CopilotClient.setForegroundSessionId() is documented for TUI + --ui-server, not the App extension host.
• sessions.open({ kind: "resume" }) restores runtime state but does not focus Chat View.
• commands.execute({ commandName: "resume" }) fails because the App does not own that command.
• commands.enqueue("/resume ...") may accept the command without executing a UI transition.
• session.send() sends a user turn to the extension's currently joined session; it cannot target the newly forked session and should not be used as a navigation workaround.
• ghapp://sessions/SESSION_ID targets an App session, but no public API maps a forked runtime session ID to an App session ID.

The only reliable fallback is asking the user to manually run /resume <sessionId>.

Proposed solution

Add a capability-gated API that resolves a local runtime session and opens or focuses its corresponding App Chat View.

A possible contract:

if (session.capabilities.ui?.openLocalSession) {
    const result = await session.ui.openLocalSession({
        runtimeSessionId,
        focus: true,
    });
}

Example result:

{
    status: "opened",
    runtimeSessionId,
    appSessionId
}

The operation should:

• Resolve only after Chat View has committed the session change.
• Create or resolve the corresponding App session record when necessary.
• Return typed failures such as not_found, in_use, unsupported, and denied.
• Be advertised through host capabilities.
• Restrict access to local sessions available to the current user.
• Allow the host to request user confirmation when appropriate.

Navigation should remain separate from message sending.

Workflow impact

This would let Canvas extensions implement reliable Open Chat and Fork and open actions.

It would benefit session visualizers, task boards, workflow canvases, and other extensions that represent App sessions. It would also remove the need for synthetic user messages, private RPC calls, guessed deep links, or fire-and-forget /resume commands.

Installation context

User-scoped Canvas extension registered through joinSession({ canvases: [...] }) in a local branch workspace.

Observed with GitHub Copilot App / CLI 1.0.80 on Windows.

Additional context

This is related to #1284, which proposes a broader bridge from Canvas extensions to App host capabilities. This request is intentionally narrower: resolve a local runtime session ID, open or focus it in Chat View, and report completion.

Relevant SDK contracts:

• Canvas lifecycle: https://github.com/github/copilot-sdk/blob/ea41dadb199725766d5097f4592c17be3200035f/nodejs/src/canvas.ts#L15-L24
• Foreground session API: https://github.com/github/copilot-sdk/blob/ea41dadb199725766d5097f4592c17be3200035f/nodejs/src/client.ts#L2294-L2348
• Extension joinSession(): https://github.com/github/copilot-sdk/blob/ea41dadb199725766d5097f4592c17be3200035f/nodejs/src/extension.ts#L96-L137
• App deep links: https://docs.github.com/en/copilot/how-tos/github-copilot-app/open-with-deep-links#available-app-links