session-event-types.test.ts

/**
 * Regression test for #1156: dedicated session event data/payload types are
 * importable from the package entry point (`@github/copilot-sdk` /
 * `src/index.js`).
 *
 * Before this fix, only the aggregate `SessionEvent` discriminated union was
 * re-exported. The constituent `*Event` wrapper interfaces and their `*Data`
 * payload types lived in `generated/session-events.ts` and could only be
 * reached via a deep import (`@github/copilot-sdk/dist/generated/...`).
 *
 * Most of this file exercises the *type* surface — if these type-only imports
 * compile, the public API exposes the types. The runtime assertions below only
 * validate representative object shapes for those annotations; they do not
 * prove that type-only exports exist at runtime.
 */

import { describe, expect, it } from "vitest";
import { approveAll } from "../src/index.js";
import { FACTORY_AGENT_OPTION_KEYS } from "../src/factory.js";
import type { FactoryAgentOptions as WireFactoryAgentOptions } from "../src/generated/rpc.js";
import type {
    // The aggregate union; must still resolve via the package root.
    SessionEvent,
    AutoTier,
    AutoTierSwitchFailedData,
    AutoTierSwitchFailedEvent,
    AutoTierSwitchFailureReason,
    CapiSessionOptions,
    PermissionRequest,
    PermissionRequestedData,
    PermissionRequestedEvent,
    PermissionResponseCapability,
    ManagedSettingsResolvedData,
    ManagedSettingsResolvedEvent,
    ManagedSettingsResolvedSource,

    // *Data payload types from the v0.3.0 generated session-event schema.
    AssistantMessageData,
    AssistantMessageDeltaData,
    AssistantReasoningData,
    AssistantTurnStartData,
    ErrorData,
    IdleData,
    ResumeData,
    StartData,
    ToolExecutionCompleteData,
    ToolExecutionPartialData,
    ToolExecutionProgressData,
    ToolExecutionStartData,
    UserMessageData,

    // *Event wrapper interfaces.
    AssistantMessageEvent,
    ErrorEvent,
    IdleEvent,
    ResumeEvent,
    StartEvent,
    ToolExecutionCompleteEvent,
    ToolExecutionStartEvent,
    UserMessageEvent,

    // A sample of supporting auxiliary aliases/unions referenced by the
    // *Data shapes — these must also be reachable so that consumers can
    // narrow or annotate intermediate values.
    UserMessageAgentMode,
    Attachment,
    WorkingDirectoryContextHostType,
    FactoryContext,
    FactoryDefinition,
    FactoryAgentOptions,
    FactoryRunResult,
    JsonValue,
} from "../src/index.js";

/**
 * Type-only helper: forces the compiler to resolve the supplied type
 * parameter. If the type is not exported from `../src/index.js`, the file
 * fails to type-check and the test never runs. There is no runtime body —
 * the helper exists purely to make "is this type importable?" assertions
 * compile-time checked.
 */
function assertImportable<_T>(): void {
    /* no-op; compile-time check only */
}

/**
 * Compile-time mutual-assignability check: passes only when `A` and `B`
 * are structurally equivalent. Used below to pin the package-root
 * `AssistantMessageEvent` (which is explicitly re-exported from
 * `./session.js` and therefore shadows the generated `AssistantMessageEvent`
 * arriving via `export type *`) to the corresponding arm of the generated
 * `SessionEvent` union. If a future schema regen ever caused these two
 * shapes to drift, this assertion would fail to type-check and `npm run
 * typecheck` would surface it before the public API silently changed.
 */
type _AssertEqual<A, B> =
    (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2 ? true : false;
type _AssistantMessageEventStaysAlignedWithSessionEventUnion = _AssertEqual<
    AssistantMessageEvent,
    Extract<SessionEvent, { type: "assistant.message" }>
>;
const _assistantMessageEventAlignmentCheck: _AssistantMessageEventStaysAlignedWithSessionEventUnion = true;
type _DefaultFactoryArgsAreJsonValue = _AssertEqual<FactoryContext["args"], JsonValue>;
const _defaultFactoryArgsCheck: _DefaultFactoryArgsAreJsonValue = true;
type _DefaultFactoryResultIsJsonValueOrVoid = _AssertEqual<
    Awaited<ReturnType<FactoryDefinition["run"]>>,
    JsonValue | void
>;
const _defaultFactoryResultCheck: _DefaultFactoryResultIsJsonValueOrVoid = true;
type _FactoryRunResultIsJsonValueOrUndefined = _AssertEqual<
    FactoryRunResult["result"],
    JsonValue | undefined
>;
const _factoryRunResultCheck: _FactoryRunResultIsJsonValueOrUndefined = true;
type _FactoryAgentOptionKeysMatchPublicInterface = _AssertEqual<
    (typeof FACTORY_AGENT_OPTION_KEYS)[number],
    keyof FactoryAgentOptions
>;
const _factoryAgentOptionKeysCheck: _FactoryAgentOptionKeysMatchPublicInterface = true;
type _PublicFactoryAgentOptionsMatchWire = _AssertEqual<
    keyof FactoryAgentOptions,
    keyof WireFactoryAgentOptions
>;
const _publicFactoryAgentOptionsCheck: _PublicFactoryAgentOptionsMatchWire = true;
// @ts-expect-error Factory arguments must be representable on the JSON wire.
type _FactoryArgsRejectUndefined = FactoryContext<undefined>;
// @ts-expect-error Factory results must be JSON values or top-level void.
type _FactoryResultRejectsFunction = FactoryDefinition<JsonValue, () => void>;
type _PermissionRequestedEventStaysAlignedWithSessionEventUnion = _AssertEqual<
    PermissionRequestedEvent,
    Extract<SessionEvent, { type: "permission.requested" }>
>;
const _permissionRequestedEventAlignmentCheck: _PermissionRequestedEventStaysAlignedWithSessionEventUnion = true;

describe("Session event type exports (#1156)", () => {
    it.each(["efficiency", "balance", "intelligence", undefined] satisfies (
        | AutoTier
        | undefined
    )[])("exposes Auto tier %s on start and resume data", (autoTier) => {
        const start: StartData = {
            copilotVersion: "1.0.82-1",
            producer: "copilot-agent",
            sessionId: "session-1",
            startTime: "2026-08-28T00:00:00Z",
            version: 1,
            autoTier,
        };
        const resume: ResumeData = {
            eventCount: 1,
            resumeTime: "2026-08-28T00:01:00Z",
            autoTier,
        };
        const capi: CapiSessionOptions = { autoTier: start.autoTier };
        expect(capi.autoTier).toBe(autoTier);
        expect(resume.autoTier).toBe(autoTier);
        if (autoTier === undefined) {
            expect(JSON.parse(JSON.stringify(start))).not.toHaveProperty("autoTier");
            expect(JSON.parse(JSON.stringify(resume))).not.toHaveProperty("autoTier");
        }
    });

    it.each([
        "policy_rejected",
        "request_failed",
        "setup_failed",
        "unsupported",
    ] satisfies AutoTierSwitchFailureReason[])(
        "exposes the Auto tier switch failure event with reason %s",
        (reason) => {
            const data: AutoTierSwitchFailedData = {
                reason,
                requestedAutoTier: "intelligence",
                effectiveAutoTier: "balance",
            };
            const event: AutoTierSwitchFailedEvent = {
                type: "session.auto_tier_switch_failed",
                id: "event-1",
                parentId: null,
                timestamp: "2026-09-02T00:00:00Z",
                ephemeral: true,
                data,
            };

            // The failure event must be reachable through the aggregate union so
            // consumers can narrow on it in a single event handler.
            const asSessionEvent: SessionEvent = event;
            expect(asSessionEvent.type).toBe("session.auto_tier_switch_failed");
            expect(data.reason).toBe(reason);
            expect(data.requestedAutoTier).toBe("intelligence");
        }
    );

    it("allows a null requested Auto tier when returning to default routing fails", () => {
        const data: AutoTierSwitchFailedData = {
            reason: "unsupported",
            requestedAutoTier: null,
        };
        expect(data.requestedAutoTier).toBeNull();
        expect(data.effectiveAutoTier).toBeUndefined();
    });

    it("exposes the headline ToolExecutionStartData type with a usable shape", () => {
        // This is the specific type called out in issue #1156. The annotation
        // is the compile-time API-surface check; these assertions only validate
        // the representative runtime object shape a consumer would use.
        const data: ToolExecutionStartData = {
            toolCallId: "call-1",
            toolName: "shell",
            arguments: { command: "ls" },
            mcpServerName: "filesystem",
            mcpToolName: "list_dir",
            turnId: "turn-1",
        };

        expect(data.toolName).toBe("shell");
        expect(data.toolCallId).toBe("call-1");
        expect(data.arguments).toEqual({ command: "ls" });
        expect(data.mcpServerName).toBe("filesystem");
        expect(data.mcpToolName).toBe("list_dir");
        expect(data.turnId).toBe("turn-1");
    });

    it("exposes explicit user approval metadata for managed Domain requests", () => {
        const request: PermissionRequest = {
            kind: "url",
            url: "https://api.example.com/data",
            intention: "Fetch domain data",
            managedApprovalRequired: true,
        };

        expect(request.managedApprovalRequired).toBe(true);
    });

    it("exposes managed approval metadata through permission event types", () => {
        const data: PermissionRequestedData = {
            permissionRequest: {
                kind: "url",
                url: "https://api.example.com/data",
                intention: "Fetch domain data",
                managedApprovalRequired: true,
            },
            requestId: "permission-1",
        };
        const event: SessionEvent = {
            id: "evt-permission-1",
            parentId: null,
            timestamp: "2026-01-01T00:00:00.000Z",
            type: "permission.requested",
            data,
        };

        if (event.type !== "permission.requested") {
            throw new Error("expected permission.requested narrowing");
        }

        const permissionEvent: PermissionRequestedEvent = event;
        expect(permissionEvent.data.permissionRequest.managedApprovalRequired).toBe(true);
    });

    it("exposes managed settings client and mixed provenance", () => {
        const sources: ManagedSettingsResolvedSource[] = [
            "server",
            "device",
            "client",
            "mixed",
            "none",
        ];
        expect(sources).toEqual(["server", "device", "client", "mixed", "none"]);

        const clientData: ManagedSettingsResolvedData = {
            bypassPermissionsDisabled: true,
            clientManaged: true,
            deviceManaged: false,
            failClosed: false,
            managedKeys: ["permissions"],
            serverManaged: false,
            source: "client",
        };
        const clientEvent: ManagedSettingsResolvedEvent = {
            ephemeral: true,
            id: "evt-managed-1",
            parentId: null,
            timestamp: "2026-01-01T00:00:00.000Z",
            type: "session.managed_settings_resolved",
            data: clientData,
        };
        expect(clientEvent.data.source).toBe("client");
        expect(clientEvent.data.clientManaged).toBe(true);

        const { clientManaged: _, ...withoutClientManaged } = clientData;
        const mixedData: ManagedSettingsResolvedData = {
            ...withoutClientManaged,
            source: "mixed",
        };
        expect(mixedData.source).toBe("mixed");
        expect("clientManaged" in mixedData).toBe(false);
    });

    it("rejects approveAll in managed settings sessions", () => {
        expect(() =>
            approveAll(
                {
                    kind: "url",
                    url: "https://api.example.com/data",
                    intention: "Fetch ordinary data",
                },
                { sessionId: "session-1", managedSettingsEnabled: true }
            )
        ).toThrow("approveAll cannot be used when managed settings are enabled");

        expect(() =>
            approveAll(
                {
                    kind: "url",
                    url: "https://api.example.com/data",
                    intention: "Fetch managed data",
                    managedApprovalRequired: true,
                },
                { sessionId: "session-1", managedSettingsEnabled: true }
            )
        ).toThrow("approveAll cannot be used when managed settings are enabled");
    });

    it("leaves managed requests pending when managed settings are disabled", () => {
        expect(
            approveAll(
                {
                    kind: "url",
                    url: "https://api.example.com/data",
                    intention: "Fetch managed data",
                    managedApprovalRequired: true,
                },
                { sessionId: "session-1", managedSettingsEnabled: false }
            )
        ).toEqual({ kind: "no-result" });
    });

    it("wraps ToolExecutionStartData inside the exported ToolExecutionStartEvent", () => {
        const event: ToolExecutionStartEvent = {
            id: "evt-1",
            parentId: null,
            timestamp: "2026-01-01T00:00:00.000Z",
            type: "tool.execution_start",
            data: {
                toolCallId: "call-1",
                toolName: "shell",
            },
        };

        expect(event.type).toBe("tool.execution_start");
        expect(event.data.toolName).toBe("shell");
        expect(event.parentId).toBeNull();
    });

    it("narrows the aggregate SessionEvent union to a dedicated *Data type", () => {
        const evt: SessionEvent = {
            id: "evt-2",
            parentId: null,
            timestamp: "2026-01-01T00:00:01.000Z",
            type: "tool.execution_start",
            data: {
                toolCallId: "call-2",
                toolName: "shell",
            },
        };

        if (evt.type !== "tool.execution_start") {
            throw new Error("expected tool.execution_start narrowing");
        }

        // After narrowing, `evt.data` must satisfy `ToolExecutionStartData`.
        // Annotating the local with the dedicated *Data type proves the
        // re-export is wired up correctly.
        const data: ToolExecutionStartData = evt.data;
        expect(data.toolCallId).toBe("call-2");
        expect(data.toolName).toBe("shell");
    });

    it("re-exports the full set of *Data and *Event types named in v0.3.0", () => {
        // Compile-time checks: if any of these fail to resolve, the file
        // will not type-check and the test will not be executed.
        assertImportable<AssistantMessageData>();
        assertImportable<AssistantMessageDeltaData>();
        assertImportable<AssistantReasoningData>();
        assertImportable<AssistantTurnStartData>();
        assertImportable<ErrorData>();
        assertImportable<IdleData>();
        assertImportable<ResumeData>();
        assertImportable<StartData>();
        assertImportable<ToolExecutionCompleteData>();
        assertImportable<ToolExecutionPartialData>();
        assertImportable<ToolExecutionProgressData>();
        assertImportable<ToolExecutionStartData>();
        assertImportable<UserMessageData>();
        assertImportable<PermissionRequestedData>();
        assertImportable<PermissionResponseCapability>();
        assertImportable<ManagedSettingsResolvedData>();

        assertImportable<AssistantMessageEvent>();
        assertImportable<ErrorEvent>();
        assertImportable<IdleEvent>();
        assertImportable<ResumeEvent>();
        assertImportable<StartEvent>();
        assertImportable<ToolExecutionCompleteEvent>();
        assertImportable<ToolExecutionStartEvent>();
        assertImportable<UserMessageEvent>();
        assertImportable<PermissionRequestedEvent>();
        assertImportable<ManagedSettingsResolvedEvent>();
        assertImportable<ManagedSettingsResolvedSource>();

        // Supporting auxiliary types referenced by the *Data shapes — these
        // must round-trip through the package root too, otherwise consumers
        // annotating intermediate values would still need a deep import.
        assertImportable<UserMessageAgentMode>();
        assertImportable<Attachment>();
        assertImportable<WorkingDirectoryContextHostType>();

        expect(true).toBe(true);
    });
});