@mcpfn/testing 0.0.1 → 0.0.2

package/dist/index.d.cts

@@ -1,40 +1,45 @@
-import { ClientCapabilities, Tool, CallToolResult, CreateTaskResult, Task, ListTasksResult, Resource, ResourceTemplate, ReadResourceResult, Prompt, GetPromptResult, CompleteRequest, CompleteResult } from '@modelcontextprotocol/sdk/types.js';
+import { ClientCapabilities, Implementation, Tool, CallToolResult, CreateTaskResult, Task, ListTasksResult, Resource, ResourceTemplate, ReadResourceResult, Prompt, GetPromptResult, CompleteRequest, CompleteResult, ServerCapabilities } from '@modelcontextprotocol/sdk/types.js';
 import { McpFnServer, McpFnManifest } from '@mcpfn/core';
+import { McpFnClient, McpFnClientMediatedHandlers, McpFnClientEventSink, McpFnDiagnosticSink, McpFnTarget, McpFnClientEventKind, McpFnTargetDescriptor, McpFnDiagnosticEvent } from '@mcpfn/client';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
-export { MCPFN_OAUTH_EXTENSION_GRANTS, McpFnAuthAssertionError, McpFnAuthCredential, McpFnAuthCredentialKind, McpFnAuthCredentialRequest, McpFnAuthProbeScenario, McpFnAuthProviderAdapter, McpFnAuthProviderCapabilities, McpFnAuthRegressionOptions, McpFnAuthScenarioResult, McpFnAuthTarget, McpFnBearerChallenge, McpFnFetchAuthTargetOptions, McpFnMockOAuthAuthorizationServer, McpFnMockOAuthServerOptions, McpFnMockOAuthTokenSet, McpFnOAuthCallback, McpFnOAuthClientMetadata, McpFnOAuthClientMetadataFixtureOptions, McpFnOAuthClientMetadataVariants, McpFnPkcePair, McpFnStartMockOAuthServerOptions, McpFnStartedMockOAuthServer, apiKeyCredential, assertAuthRegressionSuite, assertAuthorizationCodeClientMetadata, assertBearerResourceChallenge, bearerCredential, createFetchAuthTarget, createOAuthClientMetadataFixture, createOAuthClientMetadataVariants, createPkcePair, parseBearerChallenge, runAuthRegressionSuite, startMockOAuthAuthorizationServer } from './auth.cjs';
+import { RequestOptions } from '@modelcontextprotocol/sdk/shared/protocol.js';
+export { MCPFN_NAMED_OAUTH_HOST_FIXTURES, MCPFN_OAUTH_EXTENSION_GRANTS, McpFnAuthAssertionError, McpFnAuthCredential, McpFnAuthCredentialKind, McpFnAuthCredentialRequest, McpFnAuthProbeScenario, McpFnAuthProviderAdapter, McpFnAuthProviderCapabilities, McpFnAuthRegressionOptions, McpFnAuthScenarioResult, McpFnAuthTarget, McpFnBearerChallenge, McpFnFetchAuthTargetOptions, McpFnMockOAuthAuthorizationServer, McpFnMockOAuthServerOptions, McpFnMockOAuthTokenSet, McpFnNamedOAuthHostFixture, McpFnOAuthCallback, McpFnOAuthClientMetadata, McpFnOAuthClientMetadataFixtureOptions, McpFnOAuthClientMetadataVariants, McpFnPkcePair, McpFnStartMockOAuthServerOptions, McpFnStartedMockOAuthServer, apiKeyCredential, assertAuthRegressionSuite, assertAuthorizationCodeClientMetadata, assertBearerResourceChallenge, bearerCredential, createFetchAuthTarget, createOAuthClientMetadataFixture, createOAuthClientMetadataVariants, createPkcePair, parseBearerChallenge, runAuthRegressionSuite, startMockOAuthAuthorizationServer } from './auth.cjs';
 import '@modelcontextprotocol/sdk/server/auth/types.js';
 
 interface McpFnTestClientOptions {
     capabilities?: ClientCapabilities;
+    handlers?: McpFnClientMediatedHandlers;
+    events?: McpFnClientEventSink;
     /** Install roots, sampling, elicitation, or notification handlers before initialize. */
     configure?(client: Client): void | Promise<void>;
+    diagnostics?: McpFnDiagnosticSink;
 }
 declare class McpFnTestClient<TContext = undefined> {
-    readonly client: Client;
-    private readonly server;
-    private closed;
+    readonly session: McpFnClient;
     private constructor();
+    get client(): Client;
     static connect<TContext>(server: McpFnServer<TContext>, info?: {
         name: string;
         version: string;
     }, options?: McpFnTestClientOptions): Promise<McpFnTestClient<TContext>>;
-    listTools(): Promise<Tool[]>;
-    callTool(name: string, args?: Record<string, unknown>): Promise<CallToolResult>;
-    createToolTask(name: string, args?: Record<string, unknown>, options?: {
+    static connectTarget<TContext = undefined>(target: McpFnTarget, info?: Implementation, options?: McpFnTestClientOptions): Promise<McpFnTestClient<TContext>>;
+    listTools(options?: RequestOptions): Promise<Tool[]>;
+    callTool(name: string, args?: Record<string, unknown>, options?: RequestOptions): Promise<CallToolResult>;
+    createToolTask(name: string, args?: Record<string, unknown>, task?: {
         ttl?: number;
-    }): Promise<CreateTaskResult>;
-    getTask(taskId: string): Promise<Task>;
-    getTaskResult(taskId: string): Promise<CallToolResult>;
-    listTasks(cursor?: string): Promise<ListTasksResult>;
-    cancelTask(taskId: string): Promise<Task>;
-    listResources(): Promise<Resource[]>;
-    listResourceTemplates(): Promise<ResourceTemplate[]>;
-    readResource(uri: string): Promise<ReadResourceResult>;
-    subscribeResource(uri: string): Promise<void>;
-    unsubscribeResource(uri: string): Promise<void>;
-    listPrompts(): Promise<Prompt[]>;
-    getPrompt(name: string, args?: Record<string, string>): Promise<GetPromptResult>;
-    complete(params: CompleteRequest["params"]): Promise<CompleteResult>;
+    }, options?: RequestOptions): Promise<CreateTaskResult>;
+    getTask(taskId: string, options?: RequestOptions): Promise<Task>;
+    getTaskResult(taskId: string, options?: RequestOptions): Promise<CallToolResult>;
+    listTasks(cursor?: string, options?: RequestOptions): Promise<ListTasksResult>;
+    cancelTask(taskId: string, options?: RequestOptions): Promise<Task>;
+    listResources(options?: RequestOptions): Promise<Resource[]>;
+    listResourceTemplates(options?: RequestOptions): Promise<ResourceTemplate[]>;
+    readResource(uri: string, options?: RequestOptions): Promise<ReadResourceResult>;
+    subscribeResource(uri: string, options?: RequestOptions): Promise<void>;
+    unsubscribeResource(uri: string, options?: RequestOptions): Promise<void>;
+    listPrompts(options?: RequestOptions): Promise<Prompt[]>;
+    getPrompt(name: string, args?: Record<string, string>, options?: RequestOptions): Promise<GetPromptResult>;
+    complete(params: CompleteRequest["params"], options?: RequestOptions): Promise<CompleteResult>;
     close(): Promise<void>;
 }
 
@@ -69,8 +74,30 @@ interface OfficialConformanceResult {
     stdout: string;
     stderr: string;
 }
+interface AuthenticatedConformanceProxy {
+    /** Loopback URL to pass to the official conformance runner. */
+    url: string;
+    close(): Promise<void>;
+}
+interface AuthenticatedConformanceProxyOptions {
+    /** Fixed loopback MCP URL. Requests cannot select a different origin or path. */
+    url: string;
+    /** Headers injected into requests using the proxy's own authority. Values are never logged. */
+    headers: HeadersInit;
+}
+interface AuthenticatedOfficialConformanceOptions extends OfficialConformanceOptions {
+    headers: HeadersInit;
+}
+/**
+ * Start a loopback-only streaming proxy for runners that cannot send auth
+ * headers. Authenticated requests use one fixed upstream authority and path.
+ * Host-manipulation probes are forwarded without injected credentials.
+ */
+declare function createAuthenticatedConformanceProxy(options: AuthenticatedConformanceProxyOptions): Promise<AuthenticatedConformanceProxy>;
 declare function buildOfficialConformanceArgs(options: OfficialConformanceOptions): string[];
 declare function runOfficialConformance(options: OfficialConformanceOptions): Promise<OfficialConformanceResult>;
+/** Run the pinned official suite against an authenticated MCP endpoint. */
+declare function runAuthenticatedOfficialConformance(options: AuthenticatedOfficialConformanceOptions): Promise<OfficialConformanceResult>;
 
 type McpFnServerFeature = "tools" | "resources" | "prompts" | "completions" | "tasks" | "logging";
 interface McpFnHostProfile {
@@ -129,8 +156,20 @@ declare const MCPFN_HOST_PROFILES: {
 };
 declare function checkHostCompatibility(manifest: McpFnManifest, profile: McpFnHostProfile): McpFnHostCompatibilityResult;
 
-interface McpFnScenario {
+type McpFnScenarioSideEffect = "none" | "idempotent" | "non-idempotent";
+interface McpFnScenarioBase {
+    formatVersion?: 1;
     name: string;
+    /** Defaults to the runner timeout. */
+    timeoutMs?: number;
+    sideEffect?: McpFnScenarioSideEffect;
+    status?: "complete" | "incomplete";
+    incompleteReason?: string;
+    /** Environment-backed placeholders used by this scenario, never their values. */
+    variables?: string[];
+}
+interface McpFnToolScenario extends McpFnScenarioBase {
+    kind?: "tools.call";
     tool: string;
     arguments?: Record<string, unknown>;
     expect?: {
@@ -140,13 +179,190 @@ interface McpFnScenario {
     };
     verify?(result: CallToolResult): void | Promise<void>;
 }
+interface McpFnInventoryScenario extends McpFnScenarioBase {
+    kind: "tools.list" | "resources.list" | "resources.templates.list" | "prompts.list";
+    expectNames?: string[];
+}
+interface McpFnResourceScenario extends McpFnScenarioBase {
+    kind: "resources.read" | "resources.subscribe" | "resources.unsubscribe";
+    uri: string;
+    expect?: unknown;
+}
+interface McpFnPromptScenario extends McpFnScenarioBase {
+    kind: "prompts.get";
+    prompt: string;
+    arguments?: Record<string, string>;
+    expect?: unknown;
+}
+interface McpFnInitializeScenario extends McpFnScenarioBase {
+    kind: "initialize";
+    expectCapabilities?: Record<string, unknown>;
+}
+interface McpFnCreateTaskScenario extends McpFnScenarioBase {
+    kind: "tools.call:task";
+    tool: string;
+    arguments?: Record<string, unknown>;
+    task?: {
+        ttl?: number;
+    };
+    expect?: unknown;
+}
+interface McpFnTaskScenario extends McpFnScenarioBase {
+    kind: "tasks.get" | "tasks.result" | "tasks.cancel" | "tasks.list";
+    taskId?: string;
+    cursor?: string;
+    expect?: unknown;
+}
+interface McpFnEventScenario extends McpFnScenarioBase {
+    kind: "events.expect";
+    event: McpFnClientEventKind;
+    minimum?: number;
+    expectPayload?: unknown;
+}
+interface McpFnAuthScenario extends McpFnScenarioBase {
+    kind: "auth.assert";
+    phase: string;
+    expect: {
+        outcome: "allowed" | "denied";
+        code?: string;
+    };
+    input?: Record<string, unknown>;
+}
+type McpFnScenario = McpFnToolScenario | McpFnInventoryScenario | McpFnResourceScenario | McpFnPromptScenario | McpFnInitializeScenario | McpFnCreateTaskScenario | McpFnTaskScenario | McpFnEventScenario | McpFnAuthScenario;
+interface McpFnScenarioArtifact {
+    formatVersion: 1;
+    kind: "mcpfn.scenarios";
+    status: "complete" | "incomplete";
+    scenarios: McpFnScenario[];
+    variables?: string[];
+    incompleteReason?: string;
+}
+type McpFnRecordedOperation = {
+    kind: "tools.call";
+    name: string;
+    arguments?: Record<string, unknown>;
+} | {
+    kind: "tools.call:task";
+    name: string;
+    arguments?: Record<string, unknown>;
+    task?: {
+        ttl?: number;
+    };
+} | {
+    kind: "resources.read";
+    uri: string;
+} | {
+    kind: "resources.subscribe";
+    uri: string;
+} | {
+    kind: "resources.unsubscribe";
+    uri: string;
+} | {
+    kind: "prompts.get";
+    name: string;
+    arguments?: Record<string, string>;
+} | {
+    kind: "tasks.get";
+    taskId: string;
+} | {
+    kind: "tasks.result";
+    taskId: string;
+} | {
+    kind: "tasks.cancel";
+    taskId: string;
+} | {
+    kind: "tasks.list";
+    cursor?: string;
+};
+type McpFnRecordedOperationResult = CallToolResult | ReadResourceResult | GetPromptResult | CreateTaskResult | Task | ListTasksResult | void;
 interface McpFnScenarioResult {
+    formatVersion: 1;
     name: string;
-    tool: string;
-    status: "passed" | "failed";
+    operation: string;
+    tool?: string;
+    status: "passed" | "failed" | "incomplete";
+    sideEffect: McpFnScenarioSideEffect;
     durationMs: number;
     error?: string;
+    /** Observed client events discarded while this scenario was running. */
+    droppedObservedEvents?: number;
+}
+interface McpFnScenarioReport {
+    formatVersion: 1;
+    kind: "mcpfn.scenario-report";
+    status: "complete" | "incomplete";
+    manifestHash?: string;
+    total: number;
+    passed: number;
+    failed: number;
+    incomplete: number;
+    droppedResults: number;
+    droppedObservedEvents: number;
+    incompleteReason?: string;
+    results: McpFnScenarioResult[];
+}
+/** Convert an observed production-client operation into the shared runner contract. */
+declare function createMcpFnScenario(name: string, operation: McpFnRecordedOperation, result: McpFnRecordedOperationResult): McpFnScenario;
+/** Validate an unknown scenario module before it reaches the shared runner. */
+declare function validateMcpFnScenarios(value: unknown): McpFnScenario[];
+declare function createMcpFnScenarioArtifact(scenarios: McpFnScenario[], options?: Omit<McpFnScenarioArtifact, "formatVersion" | "kind" | "scenarios">): McpFnScenarioArtifact;
+declare function runScenarios(client: McpFnTestClient<unknown>, scenarios: McpFnScenario[], options?: McpFnScenarioRunOptions): Promise<McpFnScenarioResult[]>;
+interface McpFnScenarioRunOptions {
+    defaultTimeoutMs?: number;
+    maxScenarios?: number;
+    maxErrorBytes?: number;
+    /** Observed client-event count cap. Defaults to 500. */
+    maxObservedEvents?: number;
+    variables?: Record<string, string | undefined>;
+    auth?(scenario: McpFnAuthScenario, signal: AbortSignal): Promise<{
+        outcome: "allowed" | "denied";
+        code?: string;
+    }>;
+}
+declare function createMcpFnScenarioReport(results: McpFnScenarioResult[], options?: {
+    manifestHash?: string;
+    maxBytes?: number;
+}): McpFnScenarioReport;
+
+interface RunMcpFnTargetSuiteOptions {
+    target: McpFnTarget;
+    scenarios?: McpFnScenario[];
+    manifest?: McpFnManifest;
+    expectedToolNames?: readonly string[];
+    clientInfo?: Implementation;
+    client?: McpFnTestClientOptions;
+    scenarioRun?: NonNullable<Parameters<typeof runScenarios>[2]>;
+    /** Aggregate JSON size cap. Defaults to 1 MiB. */
+    maxReportBytes?: number;
+    /** Diagnostic timeline count cap. Defaults to 500. */
+    maxTimelineEvents?: number;
+}
+interface McpFnTargetSuiteReport {
+    formatVersion: 1;
+    kind: "mcpfn.target-suite-report";
+    status: "complete" | "incomplete";
+    runtime: {
+        node: string;
+        scenarioFormatVersion: 1;
+    };
+    ok: boolean;
+    target: McpFnTargetDescriptor;
+    server?: Implementation;
+    capabilities?: ServerCapabilities;
+    manifestChecked: boolean;
+    manifestHash?: string;
+    total: number;
+    passed: number;
+    failed: number;
+    incomplete: number;
+    droppedResults: number;
+    droppedObservedEvents: number;
+    incompleteReason?: string;
+    timeline: McpFnDiagnosticEvent[];
+    droppedTimelineEvents: number;
+    results: McpFnScenarioResult[];
 }
-declare function runScenarios(client: McpFnTestClient<unknown>, scenarios: McpFnScenario[]): Promise<McpFnScenarioResult[]>;
+/** Runs local, stdio, HTTP, or custom targets through the production session engine. */
+declare function runMcpFnTargetSuite(options: RunMcpFnTargetSuiteOptions): Promise<McpFnTargetSuiteReport>;
 
-export { type AssertManifestContractOptions, MCPFN_HOST_PROFILES, McpFnAssertionError, type McpFnHostCompatibilityIssue, type McpFnHostCompatibilityResult, type McpFnHostProfile, type McpFnScenario, type McpFnScenarioResult, type McpFnServerFeature, McpFnTestClient, type McpFnTestClientOptions, OFFICIAL_CONFORMANCE_VERSION, type OfficialConformanceOptions, type OfficialConformanceResult, assertManifestContract, assertStructuredTextParity, buildOfficialConformanceArgs, checkHostCompatibility, runOfficialConformance, runScenarios, stableJson };
+export { type AssertManifestContractOptions, type AuthenticatedConformanceProxy, type AuthenticatedConformanceProxyOptions, type AuthenticatedOfficialConformanceOptions, MCPFN_HOST_PROFILES, McpFnAssertionError, type McpFnAuthScenario, type McpFnCreateTaskScenario, type McpFnEventScenario, type McpFnHostCompatibilityIssue, type McpFnHostCompatibilityResult, type McpFnHostProfile, type McpFnInitializeScenario, type McpFnInventoryScenario, type McpFnPromptScenario, type McpFnRecordedOperation, type McpFnRecordedOperationResult, type McpFnResourceScenario, type McpFnScenario, type McpFnScenarioArtifact, type McpFnScenarioBase, type McpFnScenarioReport, type McpFnScenarioResult, type McpFnScenarioRunOptions, type McpFnScenarioSideEffect, type McpFnServerFeature, type McpFnTargetSuiteReport, type McpFnTaskScenario, McpFnTestClient, type McpFnTestClientOptions, type McpFnToolScenario, OFFICIAL_CONFORMANCE_VERSION, type OfficialConformanceOptions, type OfficialConformanceResult, type RunMcpFnTargetSuiteOptions, assertManifestContract, assertStructuredTextParity, buildOfficialConformanceArgs, checkHostCompatibility, createAuthenticatedConformanceProxy, createMcpFnScenario, createMcpFnScenarioArtifact, createMcpFnScenarioReport, runAuthenticatedOfficialConformance, runMcpFnTargetSuite, runOfficialConformance, runScenarios, stableJson, validateMcpFnScenarios };

package/dist/index.d.ts

@@ -1,40 +1,45 @@
-import { ClientCapabilities, Tool, CallToolResult, CreateTaskResult, Task, ListTasksResult, Resource, ResourceTemplate, ReadResourceResult, Prompt, GetPromptResult, CompleteRequest, CompleteResult } from '@modelcontextprotocol/sdk/types.js';
+import { ClientCapabilities, Implementation, Tool, CallToolResult, CreateTaskResult, Task, ListTasksResult, Resource, ResourceTemplate, ReadResourceResult, Prompt, GetPromptResult, CompleteRequest, CompleteResult, ServerCapabilities } from '@modelcontextprotocol/sdk/types.js';
 import { McpFnServer, McpFnManifest } from '@mcpfn/core';
+import { McpFnClient, McpFnClientMediatedHandlers, McpFnClientEventSink, McpFnDiagnosticSink, McpFnTarget, McpFnClientEventKind, McpFnTargetDescriptor, McpFnDiagnosticEvent } from '@mcpfn/client';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
-export { MCPFN_OAUTH_EXTENSION_GRANTS, McpFnAuthAssertionError, McpFnAuthCredential, McpFnAuthCredentialKind, McpFnAuthCredentialRequest, McpFnAuthProbeScenario, McpFnAuthProviderAdapter, McpFnAuthProviderCapabilities, McpFnAuthRegressionOptions, McpFnAuthScenarioResult, McpFnAuthTarget, McpFnBearerChallenge, McpFnFetchAuthTargetOptions, McpFnMockOAuthAuthorizationServer, McpFnMockOAuthServerOptions, McpFnMockOAuthTokenSet, McpFnOAuthCallback, McpFnOAuthClientMetadata, McpFnOAuthClientMetadataFixtureOptions, McpFnOAuthClientMetadataVariants, McpFnPkcePair, McpFnStartMockOAuthServerOptions, McpFnStartedMockOAuthServer, apiKeyCredential, assertAuthRegressionSuite, assertAuthorizationCodeClientMetadata, assertBearerResourceChallenge, bearerCredential, createFetchAuthTarget, createOAuthClientMetadataFixture, createOAuthClientMetadataVariants, createPkcePair, parseBearerChallenge, runAuthRegressionSuite, startMockOAuthAuthorizationServer } from './auth.js';
+import { RequestOptions } from '@modelcontextprotocol/sdk/shared/protocol.js';
+export { MCPFN_NAMED_OAUTH_HOST_FIXTURES, MCPFN_OAUTH_EXTENSION_GRANTS, McpFnAuthAssertionError, McpFnAuthCredential, McpFnAuthCredentialKind, McpFnAuthCredentialRequest, McpFnAuthProbeScenario, McpFnAuthProviderAdapter, McpFnAuthProviderCapabilities, McpFnAuthRegressionOptions, McpFnAuthScenarioResult, McpFnAuthTarget, McpFnBearerChallenge, McpFnFetchAuthTargetOptions, McpFnMockOAuthAuthorizationServer, McpFnMockOAuthServerOptions, McpFnMockOAuthTokenSet, McpFnNamedOAuthHostFixture, McpFnOAuthCallback, McpFnOAuthClientMetadata, McpFnOAuthClientMetadataFixtureOptions, McpFnOAuthClientMetadataVariants, McpFnPkcePair, McpFnStartMockOAuthServerOptions, McpFnStartedMockOAuthServer, apiKeyCredential, assertAuthRegressionSuite, assertAuthorizationCodeClientMetadata, assertBearerResourceChallenge, bearerCredential, createFetchAuthTarget, createOAuthClientMetadataFixture, createOAuthClientMetadataVariants, createPkcePair, parseBearerChallenge, runAuthRegressionSuite, startMockOAuthAuthorizationServer } from './auth.js';
 import '@modelcontextprotocol/sdk/server/auth/types.js';
 
 interface McpFnTestClientOptions {
     capabilities?: ClientCapabilities;
+    handlers?: McpFnClientMediatedHandlers;
+    events?: McpFnClientEventSink;
     /** Install roots, sampling, elicitation, or notification handlers before initialize. */
     configure?(client: Client): void | Promise<void>;
+    diagnostics?: McpFnDiagnosticSink;
 }
 declare class McpFnTestClient<TContext = undefined> {
-    readonly client: Client;
-    private readonly server;
-    private closed;
+    readonly session: McpFnClient;
     private constructor();
+    get client(): Client;
     static connect<TContext>(server: McpFnServer<TContext>, info?: {
         name: string;
         version: string;
     }, options?: McpFnTestClientOptions): Promise<McpFnTestClient<TContext>>;
-    listTools(): Promise<Tool[]>;
-    callTool(name: string, args?: Record<string, unknown>): Promise<CallToolResult>;
-    createToolTask(name: string, args?: Record<string, unknown>, options?: {
+    static connectTarget<TContext = undefined>(target: McpFnTarget, info?: Implementation, options?: McpFnTestClientOptions): Promise<McpFnTestClient<TContext>>;
+    listTools(options?: RequestOptions): Promise<Tool[]>;
+    callTool(name: string, args?: Record<string, unknown>, options?: RequestOptions): Promise<CallToolResult>;
+    createToolTask(name: string, args?: Record<string, unknown>, task?: {
         ttl?: number;
-    }): Promise<CreateTaskResult>;
-    getTask(taskId: string): Promise<Task>;
-    getTaskResult(taskId: string): Promise<CallToolResult>;
-    listTasks(cursor?: string): Promise<ListTasksResult>;
-    cancelTask(taskId: string): Promise<Task>;
-    listResources(): Promise<Resource[]>;
-    listResourceTemplates(): Promise<ResourceTemplate[]>;
-    readResource(uri: string): Promise<ReadResourceResult>;
-    subscribeResource(uri: string): Promise<void>;
-    unsubscribeResource(uri: string): Promise<void>;
-    listPrompts(): Promise<Prompt[]>;
-    getPrompt(name: string, args?: Record<string, string>): Promise<GetPromptResult>;
-    complete(params: CompleteRequest["params"]): Promise<CompleteResult>;
+    }, options?: RequestOptions): Promise<CreateTaskResult>;
+    getTask(taskId: string, options?: RequestOptions): Promise<Task>;
+    getTaskResult(taskId: string, options?: RequestOptions): Promise<CallToolResult>;
+    listTasks(cursor?: string, options?: RequestOptions): Promise<ListTasksResult>;
+    cancelTask(taskId: string, options?: RequestOptions): Promise<Task>;
+    listResources(options?: RequestOptions): Promise<Resource[]>;
+    listResourceTemplates(options?: RequestOptions): Promise<ResourceTemplate[]>;
+    readResource(uri: string, options?: RequestOptions): Promise<ReadResourceResult>;
+    subscribeResource(uri: string, options?: RequestOptions): Promise<void>;
+    unsubscribeResource(uri: string, options?: RequestOptions): Promise<void>;
+    listPrompts(options?: RequestOptions): Promise<Prompt[]>;
+    getPrompt(name: string, args?: Record<string, string>, options?: RequestOptions): Promise<GetPromptResult>;
+    complete(params: CompleteRequest["params"], options?: RequestOptions): Promise<CompleteResult>;
     close(): Promise<void>;
 }
 
@@ -69,8 +74,30 @@ interface OfficialConformanceResult {
     stdout: string;
     stderr: string;
 }
+interface AuthenticatedConformanceProxy {
+    /** Loopback URL to pass to the official conformance runner. */
+    url: string;
+    close(): Promise<void>;
+}
+interface AuthenticatedConformanceProxyOptions {
+    /** Fixed loopback MCP URL. Requests cannot select a different origin or path. */
+    url: string;
+    /** Headers injected into requests using the proxy's own authority. Values are never logged. */
+    headers: HeadersInit;
+}
+interface AuthenticatedOfficialConformanceOptions extends OfficialConformanceOptions {
+    headers: HeadersInit;
+}
+/**
+ * Start a loopback-only streaming proxy for runners that cannot send auth
+ * headers. Authenticated requests use one fixed upstream authority and path.
+ * Host-manipulation probes are forwarded without injected credentials.
+ */
+declare function createAuthenticatedConformanceProxy(options: AuthenticatedConformanceProxyOptions): Promise<AuthenticatedConformanceProxy>;
 declare function buildOfficialConformanceArgs(options: OfficialConformanceOptions): string[];
 declare function runOfficialConformance(options: OfficialConformanceOptions): Promise<OfficialConformanceResult>;
+/** Run the pinned official suite against an authenticated MCP endpoint. */
+declare function runAuthenticatedOfficialConformance(options: AuthenticatedOfficialConformanceOptions): Promise<OfficialConformanceResult>;
 
 type McpFnServerFeature = "tools" | "resources" | "prompts" | "completions" | "tasks" | "logging";
 interface McpFnHostProfile {
@@ -129,8 +156,20 @@ declare const MCPFN_HOST_PROFILES: {
 };
 declare function checkHostCompatibility(manifest: McpFnManifest, profile: McpFnHostProfile): McpFnHostCompatibilityResult;
 
-interface McpFnScenario {
+type McpFnScenarioSideEffect = "none" | "idempotent" | "non-idempotent";
+interface McpFnScenarioBase {
+    formatVersion?: 1;
     name: string;
+    /** Defaults to the runner timeout. */
+    timeoutMs?: number;
+    sideEffect?: McpFnScenarioSideEffect;
+    status?: "complete" | "incomplete";
+    incompleteReason?: string;
+    /** Environment-backed placeholders used by this scenario, never their values. */
+    variables?: string[];
+}
+interface McpFnToolScenario extends McpFnScenarioBase {
+    kind?: "tools.call";
     tool: string;
     arguments?: Record<string, unknown>;
     expect?: {
@@ -140,13 +179,190 @@ interface McpFnScenario {
     };
     verify?(result: CallToolResult): void | Promise<void>;
 }
+interface McpFnInventoryScenario extends McpFnScenarioBase {
+    kind: "tools.list" | "resources.list" | "resources.templates.list" | "prompts.list";
+    expectNames?: string[];
+}
+interface McpFnResourceScenario extends McpFnScenarioBase {
+    kind: "resources.read" | "resources.subscribe" | "resources.unsubscribe";
+    uri: string;
+    expect?: unknown;
+}
+interface McpFnPromptScenario extends McpFnScenarioBase {
+    kind: "prompts.get";
+    prompt: string;
+    arguments?: Record<string, string>;
+    expect?: unknown;
+}
+interface McpFnInitializeScenario extends McpFnScenarioBase {
+    kind: "initialize";
+    expectCapabilities?: Record<string, unknown>;
+}
+interface McpFnCreateTaskScenario extends McpFnScenarioBase {
+    kind: "tools.call:task";
+    tool: string;
+    arguments?: Record<string, unknown>;
+    task?: {
+        ttl?: number;
+    };
+    expect?: unknown;
+}
+interface McpFnTaskScenario extends McpFnScenarioBase {
+    kind: "tasks.get" | "tasks.result" | "tasks.cancel" | "tasks.list";
+    taskId?: string;
+    cursor?: string;
+    expect?: unknown;
+}
+interface McpFnEventScenario extends McpFnScenarioBase {
+    kind: "events.expect";
+    event: McpFnClientEventKind;
+    minimum?: number;
+    expectPayload?: unknown;
+}
+interface McpFnAuthScenario extends McpFnScenarioBase {
+    kind: "auth.assert";
+    phase: string;
+    expect: {
+        outcome: "allowed" | "denied";
+        code?: string;
+    };
+    input?: Record<string, unknown>;
+}
+type McpFnScenario = McpFnToolScenario | McpFnInventoryScenario | McpFnResourceScenario | McpFnPromptScenario | McpFnInitializeScenario | McpFnCreateTaskScenario | McpFnTaskScenario | McpFnEventScenario | McpFnAuthScenario;
+interface McpFnScenarioArtifact {
+    formatVersion: 1;
+    kind: "mcpfn.scenarios";
+    status: "complete" | "incomplete";
+    scenarios: McpFnScenario[];
+    variables?: string[];
+    incompleteReason?: string;
+}
+type McpFnRecordedOperation = {
+    kind: "tools.call";
+    name: string;
+    arguments?: Record<string, unknown>;
+} | {
+    kind: "tools.call:task";
+    name: string;
+    arguments?: Record<string, unknown>;
+    task?: {
+        ttl?: number;
+    };
+} | {
+    kind: "resources.read";
+    uri: string;
+} | {
+    kind: "resources.subscribe";
+    uri: string;
+} | {
+    kind: "resources.unsubscribe";
+    uri: string;
+} | {
+    kind: "prompts.get";
+    name: string;
+    arguments?: Record<string, string>;
+} | {
+    kind: "tasks.get";
+    taskId: string;
+} | {
+    kind: "tasks.result";
+    taskId: string;
+} | {
+    kind: "tasks.cancel";
+    taskId: string;
+} | {
+    kind: "tasks.list";
+    cursor?: string;
+};
+type McpFnRecordedOperationResult = CallToolResult | ReadResourceResult | GetPromptResult | CreateTaskResult | Task | ListTasksResult | void;
 interface McpFnScenarioResult {
+    formatVersion: 1;
     name: string;
-    tool: string;
-    status: "passed" | "failed";
+    operation: string;
+    tool?: string;
+    status: "passed" | "failed" | "incomplete";
+    sideEffect: McpFnScenarioSideEffect;
     durationMs: number;
     error?: string;
+    /** Observed client events discarded while this scenario was running. */
+    droppedObservedEvents?: number;
+}
+interface McpFnScenarioReport {
+    formatVersion: 1;
+    kind: "mcpfn.scenario-report";
+    status: "complete" | "incomplete";
+    manifestHash?: string;
+    total: number;
+    passed: number;
+    failed: number;
+    incomplete: number;
+    droppedResults: number;
+    droppedObservedEvents: number;
+    incompleteReason?: string;
+    results: McpFnScenarioResult[];
+}
+/** Convert an observed production-client operation into the shared runner contract. */
+declare function createMcpFnScenario(name: string, operation: McpFnRecordedOperation, result: McpFnRecordedOperationResult): McpFnScenario;
+/** Validate an unknown scenario module before it reaches the shared runner. */
+declare function validateMcpFnScenarios(value: unknown): McpFnScenario[];
+declare function createMcpFnScenarioArtifact(scenarios: McpFnScenario[], options?: Omit<McpFnScenarioArtifact, "formatVersion" | "kind" | "scenarios">): McpFnScenarioArtifact;
+declare function runScenarios(client: McpFnTestClient<unknown>, scenarios: McpFnScenario[], options?: McpFnScenarioRunOptions): Promise<McpFnScenarioResult[]>;
+interface McpFnScenarioRunOptions {
+    defaultTimeoutMs?: number;
+    maxScenarios?: number;
+    maxErrorBytes?: number;
+    /** Observed client-event count cap. Defaults to 500. */
+    maxObservedEvents?: number;
+    variables?: Record<string, string | undefined>;
+    auth?(scenario: McpFnAuthScenario, signal: AbortSignal): Promise<{
+        outcome: "allowed" | "denied";
+        code?: string;
+    }>;
+}
+declare function createMcpFnScenarioReport(results: McpFnScenarioResult[], options?: {
+    manifestHash?: string;
+    maxBytes?: number;
+}): McpFnScenarioReport;
+
+interface RunMcpFnTargetSuiteOptions {
+    target: McpFnTarget;
+    scenarios?: McpFnScenario[];
+    manifest?: McpFnManifest;
+    expectedToolNames?: readonly string[];
+    clientInfo?: Implementation;
+    client?: McpFnTestClientOptions;
+    scenarioRun?: NonNullable<Parameters<typeof runScenarios>[2]>;
+    /** Aggregate JSON size cap. Defaults to 1 MiB. */
+    maxReportBytes?: number;
+    /** Diagnostic timeline count cap. Defaults to 500. */
+    maxTimelineEvents?: number;
+}
+interface McpFnTargetSuiteReport {
+    formatVersion: 1;
+    kind: "mcpfn.target-suite-report";
+    status: "complete" | "incomplete";
+    runtime: {
+        node: string;
+        scenarioFormatVersion: 1;
+    };
+    ok: boolean;
+    target: McpFnTargetDescriptor;
+    server?: Implementation;
+    capabilities?: ServerCapabilities;
+    manifestChecked: boolean;
+    manifestHash?: string;
+    total: number;
+    passed: number;
+    failed: number;
+    incomplete: number;
+    droppedResults: number;
+    droppedObservedEvents: number;
+    incompleteReason?: string;
+    timeline: McpFnDiagnosticEvent[];
+    droppedTimelineEvents: number;
+    results: McpFnScenarioResult[];
 }
-declare function runScenarios(client: McpFnTestClient<unknown>, scenarios: McpFnScenario[]): Promise<McpFnScenarioResult[]>;
+/** Runs local, stdio, HTTP, or custom targets through the production session engine. */
+declare function runMcpFnTargetSuite(options: RunMcpFnTargetSuiteOptions): Promise<McpFnTargetSuiteReport>;
 
-export { type AssertManifestContractOptions, MCPFN_HOST_PROFILES, McpFnAssertionError, type McpFnHostCompatibilityIssue, type McpFnHostCompatibilityResult, type McpFnHostProfile, type McpFnScenario, type McpFnScenarioResult, type McpFnServerFeature, McpFnTestClient, type McpFnTestClientOptions, OFFICIAL_CONFORMANCE_VERSION, type OfficialConformanceOptions, type OfficialConformanceResult, assertManifestContract, assertStructuredTextParity, buildOfficialConformanceArgs, checkHostCompatibility, runOfficialConformance, runScenarios, stableJson };
+export { type AssertManifestContractOptions, type AuthenticatedConformanceProxy, type AuthenticatedConformanceProxyOptions, type AuthenticatedOfficialConformanceOptions, MCPFN_HOST_PROFILES, McpFnAssertionError, type McpFnAuthScenario, type McpFnCreateTaskScenario, type McpFnEventScenario, type McpFnHostCompatibilityIssue, type McpFnHostCompatibilityResult, type McpFnHostProfile, type McpFnInitializeScenario, type McpFnInventoryScenario, type McpFnPromptScenario, type McpFnRecordedOperation, type McpFnRecordedOperationResult, type McpFnResourceScenario, type McpFnScenario, type McpFnScenarioArtifact, type McpFnScenarioBase, type McpFnScenarioReport, type McpFnScenarioResult, type McpFnScenarioRunOptions, type McpFnScenarioSideEffect, type McpFnServerFeature, type McpFnTargetSuiteReport, type McpFnTaskScenario, McpFnTestClient, type McpFnTestClientOptions, type McpFnToolScenario, OFFICIAL_CONFORMANCE_VERSION, type OfficialConformanceOptions, type OfficialConformanceResult, type RunMcpFnTargetSuiteOptions, assertManifestContract, assertStructuredTextParity, buildOfficialConformanceArgs, checkHostCompatibility, createAuthenticatedConformanceProxy, createMcpFnScenario, createMcpFnScenarioArtifact, createMcpFnScenarioReport, runAuthenticatedOfficialConformance, runMcpFnTargetSuite, runOfficialConformance, runScenarios, stableJson, validateMcpFnScenarios };