Expose local cross-session discovery and delivery

Add session-bound Node and Rust SDK operations for listing active local peers and sending an exact-ID message through the runtime contract. Preserve typed refused, not-delivered, and ambiguous outcomes without retrying an uncertain delivery.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: ea23a388-a87d-436d-8110-4f7f543141d6

Author: dfrysinger

nodejs/src/generated/rpc.ts

@@ -11,7 +11,12 @@
 export { CopilotClient } from "./client.js";
 export { DisableBypassPermissionsModes, RuntimeConnection } from "./types.js";
 export { BuiltInTools, ToolSet } from "./toolSet.js";
-export { CopilotSession, type AssistantMessageEvent } from "./session.js";
+export {
+    CopilotSession,
+    SendSessionMessageError,
+    type AssistantMessageEvent,
+    type SendSessionMessageErrorCode,
+} from "./session.js";
 export { defineFactory, FactoryResumeError, isFactoryRunTerminal } from "./factory.js";
 export {
     Canvas,
@@ -52,6 +57,15 @@ export {
 // shadow the names arriving via `export type *`, so the hand-authored public API
 // surface for those six identifiers is preserved unchanged.
 export type * from "./generated/session-events.js";
+export type {
+    ListMessageableSessionsRequest,
+    ListMessageableSessionsResult,
+    MessageableSession,
+    SendMode,
+    SendSessionMessageRequest,
+    SendSessionMessageResult,
+    SessionMessageDelivery,
+} from "./generated/rpc.js";
 export type {
     AskUserVariant,
     CommandContext,

nodejs/src/generated/session-events.ts

@@ -18,6 +18,10 @@ import type {
     McpOauthPendingRequestResponse,
     FactoryLogLine,
     FactoryRunResult as WireFactoryRunResult,
+    ListMessageableSessionsRequest,
+    ListMessageableSessionsResult,
+    SendSessionMessageRequest,
+    SendSessionMessageResult,
 } from "./generated/rpc.js";
 import { type Canvas, CanvasError } from "./canvas.js";
 import type { OpenCanvasInstance } from "./generated/rpc.js";
@@ -382,6 +386,78 @@ function isFactoryFatalError(error: unknown): boolean {
 /** Assistant message event - the final response from the assistant. */
 export type AssistantMessageEvent = Extract<SessionEvent, { type: "assistant.message" }>;
 
+/** Stable public outcomes for a failed cross-session message send. */
+export type SendSessionMessageErrorCode = "refused" | "not-delivered" | "ambiguous";
+
+/**
+ * Error returned when the runtime reaches a recognized terminal cross-session
+ * message outcome.
+ *
+ * @experimental
+ */
+export class SendSessionMessageError extends Error {
+    constructor(
+        public readonly code: SendSessionMessageErrorCode,
+        message: string,
+        public readonly messageId?: string
+    ) {
+        super(message);
+        this.name = "SendSessionMessageError";
+    }
+}
+
+function parseSendSessionMessageErrorData(
+    data: unknown
+): { code: SendSessionMessageErrorCode; messageId?: string } | undefined {
+    if (typeof data !== "object" || data === null) {
+        return undefined;
+    }
+
+    const envelope = data as { kind?: unknown; code?: unknown; messageId?: unknown };
+    if (
+        typeof envelope.code !== "string" ||
+        (envelope.messageId !== undefined && typeof envelope.messageId !== "string")
+    ) {
+        return undefined;
+    }
+
+    let code: SendSessionMessageErrorCode;
+    switch (envelope.kind) {
+        case "session_message_refused":
+            if (
+                ![
+                    "target-not-active",
+                    "target-generation-changed",
+                    "source-not-active",
+                    "self-send",
+                    "request-invalid",
+                    "recipient-refused",
+                    "transport-unavailable",
+                ].includes(envelope.code)
+            ) {
+                return undefined;
+            }
+            code = "refused";
+            break;
+        case "session_message_not_delivered":
+            if (envelope.code !== "not-delivered") {
+                return undefined;
+            }
+            code = "not-delivered";
+            break;
+        case "session_message_ambiguous":
+            if (envelope.code !== "ambiguous") {
+                return undefined;
+            }
+            code = "ambiguous";
+            break;
+        default:
+            return undefined;
+    }
+
+    return envelope.messageId === undefined ? { code } : { code, messageId: envelope.messageId };
+}
+
 const TOOL_SEARCH_TOOL_NAME = "tool_search_tool";
 
 /**
@@ -725,6 +801,46 @@ export class CopilotSession {
         return (response as { messageId: string }).messageId;
     }
 
+    /**
+     * Lists active local sessions that this bound session can select by exact
+     * ID for cross-session messaging. The result grants no delivery authority;
+     * call {@link sendSessionMessage} with a selected `sessionId`.
+     *
+     * @experimental
+     */
+    async listMessageableSessions(
+        params: ListMessageableSessionsRequest = {}
+    ): Promise<ListMessageableSessionsResult> {
+        return this.rpc.listMessageableSessions(params);
+    }
+
+    /**
+     * Sends one authenticated non-user message from this bound session to an
+     * exact active local session.
+     *
+     * Success reports recipient admission, not completion of delegated work.
+     * An ambiguous error means delivery may have started and is never retried.
+     *
+     * @experimental
+     */
+    async sendSessionMessage(params: SendSessionMessageRequest): Promise<SendSessionMessageResult> {
+        try {
+            return await this.rpc.sendSessionMessage(params);
+        } catch (error) {
+            if (error instanceof ResponseError) {
+                const translated = parseSendSessionMessageErrorData(error.data);
+                if (translated) {
+                    throw new SendSessionMessageError(
+                        translated.code,
+                        error.message,
+                        translated.messageId
+                    );
+                }
+            }
+            throw error;
+        }
+    }
+
     /**
      * Sends a message to this session and waits until the session becomes idle.
      *

nodejs/src/index.ts

@@ -0,0 +1,115 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *--------------------------------------------------------------------------------------------*/
+
+import { readFileSync } from "node:fs";
+import { describe, expect, it, vi } from "vitest";
+import {
+    CopilotSession,
+    type ListMessageableSessionsRequest,
+    type ListMessageableSessionsResult,
+    type MessageableSession,
+} from "../src/index.js";
+
+type AssertEqual<A, B> =
+    (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2 ? true : false;
+
+type RequestMatchesPublicContract = AssertEqual<
+    ListMessageableSessionsRequest,
+    {
+        name?: string;
+    }
+>;
+const requestMatchesPublicContract: RequestMatchesPublicContract = true;
+
+type CandidateMatchesPublicContract = AssertEqual<
+    MessageableSession,
+    {
+        sessionId: string;
+        name?: string;
+        summary?: string;
+    }
+>;
+const candidateMatchesPublicContract: CandidateMatchesPublicContract = true;
+
+type ResultMatchesPublicContract = AssertEqual<
+    ListMessageableSessionsResult,
+    {
+        sessions: MessageableSession[];
+    }
+>;
+const resultMatchesPublicContract: ResultMatchesPublicContract = true;
+
+if (false) {
+    const session = null as unknown as CopilotSession;
+
+    // @ts-expect-error Source identity is derived from the bound session.
+    void session.listMessageableSessions({ sourceSessionId: "forged" });
+    // @ts-expect-error Discovery never accepts a delivery target.
+    void session.listMessageableSessions({ targetSessionId: "target-session" });
+}
+
+describe("CopilotSession.listMessageableSessions", () => {
+    it("lists all candidates when no name is supplied", async () => {
+        const result = {
+            sessions: [
+                { sessionId: "session-a", name: "Research" },
+                { sessionId: "session-b", summary: "Research" },
+            ],
+        };
+        const sendRequest = vi.fn(async () => result);
+        const session = new CopilotSession("source-session", { sendRequest } as never);
+
+        await expect(session.listMessageableSessions()).resolves.toEqual(result);
+        expect(sendRequest).toHaveBeenCalledExactlyOnceWith("session.listMessageableSessions", {
+            sessionId: "source-session",
+        });
+    });
+
+    it("forwards the exact-name query without rewriting it", async () => {
+        const result = { sessions: [{ sessionId: "session-a", name: "Research" }] };
+        const sendRequest = vi.fn(async () => result);
+        const session = new CopilotSession("source-session", { sendRequest } as never);
+
+        await expect(session.listMessageableSessions({ name: "  ReSeArCh  " })).resolves.toEqual(
+            result
+        );
+        expect(sendRequest).toHaveBeenCalledExactlyOnceWith("session.listMessageableSessions", {
+            sessionId: "source-session",
+            name: "  ReSeArCh  ",
+        });
+    });
+
+    it("does not allow untyped input to override the bound source session", async () => {
+        const result = { sessions: [] };
+        const sendRequest = vi.fn(async () => result);
+        const session = new CopilotSession("source-session", { sendRequest } as never);
+        const params = JSON.parse(
+            '{"sessionId":"forged-session","name":"Research"}'
+        ) as ListMessageableSessionsRequest;
+
+        await expect(session.listMessageableSessions(params)).resolves.toEqual(result);
+        expect(sendRequest).toHaveBeenCalledExactlyOnceWith("session.listMessageableSessions", {
+            sessionId: "source-session",
+            name: "Research",
+        });
+    });
+
+    it("keeps the generated wrapper source-bound", () => {
+        const generatedRpc = readFileSync(
+            new URL("../src/generated/rpc.ts", import.meta.url),
+            "utf8"
+        );
+
+        expect(generatedRpc).toContain(
+            "listMessageableSessions: async (params: ListMessageableSessionsRequest): Promise<ListMessageableSessionsResult> =>"
+        );
+        expect(generatedRpc).toContain(
+            'connection.sendRequest("session.listMessageableSessions", { ...params, sessionId })'
+        );
+    });
+});
+
+void requestMatchesPublicContract;
+void candidateMatchesPublicContract;
+void resultMatchesPublicContract;