@wix/pathgrade 1.0.25 → 1.0.26

package/dist/sdk/agent.js

@@ -19,6 +19,10 @@ import { cleanDebugRuns, DEFAULT_DEBUG_RETAIN_RUNS, prepareManagedDebugRun, } fr
 import { collectOpenCodeMcpToolNames, validateOpenCodeDeclaration } from '../agents/opencode/contract.js';
 import { collectSensitiveEnvValues } from '../tool-event-results.js';
 import { compileMcpMockApprovalSession, } from './mcp-mock-approvals.js';
+import { compileScenario } from './scenario-machine-v2.js';
+import { startPublicCodexScenarioRuntime } from '../agents/codex-app-server/scenario-mount.js';
+import { createPublicOpenCodeScenarioRuntimeFactory } from '../agents/opencode/scenario.js';
+import { createPublicCursorScenarioRuntimeFactory } from '../agents/cursor-scenario.js';
 import { createAskUserHandler } from './ask-bus/handler.js';
 /**
  * Test-only injection point: override the sink used by the next emitter
@@ -52,6 +56,9 @@ class AgentImpl {
     activeChatSession;
     scriptedMcp;
     sensitiveValues;
+    scenarioArtifact;
+    scenarioRuntimeFactory;
+    _scenarioEvidence = [];
     constructor(opts) {
         this.ws = opts.workspace;
         this.agentName = opts.agentName;
@@ -69,6 +76,8 @@ class AgentImpl {
         this.opencodeMcpToolNames = opts.opencodeMcpToolNames;
         this.scriptedMcp = opts.scriptedMcp;
         this.sensitiveValues = opts.sensitiveValues;
+        this.scenarioArtifact = opts.scenarioArtifact;
+        this.scenarioRuntimeFactory = opts.scenarioRuntimeFactory;
     }
     get messages() {
         return this._messages;
@@ -79,6 +88,9 @@ class AgentImpl {
     get workspace() {
         return this.ws.path;
     }
+    get scenarioEvidence() {
+        return structuredClone(this._scenarioEvidence);
+    }
     get executionMetadata() {
         const interactionMode = this.interactionMode === 'startChat'
             ? 'start_chat'
@@ -88,7 +100,9 @@ class AgentImpl {
         return {
             name: this.agentName,
             ...(this.modelOpt ? { requestedModel: this.modelOpt } : {}),
-            transport: resolveExecutionTransport(this.agentName, this.transport),
+            transport: this.scenarioArtifact && (this.agentName === 'opencode' || this.agentName === 'cursor')
+                ? 'acp'
+                : resolveExecutionTransport(this.agentName, this.transport),
             ...(interactionMode ? { interactionMode } : {}),
         };
     }
@@ -114,6 +128,9 @@ class AgentImpl {
             ...(this.opencodeExecutable !== undefined ? { opencodeExecutable: this.opencodeExecutable } : {}),
             ...(this.opencodeMcpToolNames !== undefined ? { opencodeMcpToolNames: this.opencodeMcpToolNames } : {}),
             ...(this.scriptedMcp !== undefined ? { scriptedMcp: this.scriptedMcp } : {}),
+            ...(this.scenarioArtifact !== undefined ? { scenarioArtifact: this.scenarioArtifact } : {}),
+            ...(this.scenarioRuntimeFactory !== undefined ? { scenarioRuntimeFactory: this.scenarioRuntimeFactory } : {}),
+            onScenarioEvidence: (evidence) => { this._scenarioEvidence = structuredClone(evidence); },
             sensitiveValues: this.sensitiveValues,
         });
     }
@@ -362,6 +379,7 @@ class AgentImpl {
                         conversationResult: this.lastConversationResult,
                         workspace: dest,
                         sensitiveValues: this.sensitiveValues,
+                        scenarioEvidence: this._scenarioEvidence,
                     });
                     await fs.writeJSON(path.join(dest, 'run-snapshot.json'), snapshot, { spaces: 2 });
                 }
@@ -409,10 +427,37 @@ export async function createAgent(opts) {
         }
     }
     const agentName = resolveAgentName(opts, process.env);
+    let scenarioArtifact;
+    if (opts.mcpScenario !== undefined) {
+        if (opts.agent === undefined)
+            throw new Error('mcpScenario requires an explicit agent');
+        if (opts.mcpMock !== undefined || opts.mcpMockApprovalRules !== undefined || opts.mcpConfigFile !== undefined || opts.mcpSafety !== undefined) {
+            throw new Error('mcpScenario cannot be combined with legacy or live MCP options');
+        }
+        const compiled = compileScenario(opts.mcpScenario);
+        if (!compiled.ok)
+            throw new Error(`Scenario compilation failed: ${JSON.stringify(compiled.diagnostics)}`);
+        scenarioArtifact = compiled.artifact;
+    }
     validateOpenCodeDeclaration(agentName, opts);
     const transport = agentName === 'codex'
         ? resolveCodexTransport(opts, process.env)
         : undefined;
+    if (scenarioArtifact && agentName === 'codex' && transport !== 'app-server') {
+        throw new Error('mcpScenario requires Codex transport app-server; Codex exec is unsupported');
+    }
+    const scenarioRuntimeFactory = !scenarioArtifact
+        ? undefined
+        : agentName === 'codex'
+            ? startPublicCodexScenarioRuntime
+            : agentName === 'opencode'
+                ? createPublicOpenCodeScenarioRuntimeFactory({
+                    opencodeExecutable: opts.opencodeExecutable,
+                    requestedModel: opts.model,
+                })
+                : agentName === 'cursor'
+                    ? createPublicCursorScenarioRuntimeFactory({ requestedModel: opts.model })
+                    : undefined;
     let scriptedMcp;
     if (opts.mcpMockApprovalRules !== undefined) {
         if (opts.mcpMock === undefined)
@@ -434,7 +479,7 @@ export async function createAgent(opts) {
     const timeoutSetting = opts.timeout ?? 300;
     // Capture runner context now; adapters own installation and restoration.
     const testCtx = opts.debug ? resolveCaseDebugContext() : { name: '', dir: '' };
-    const { timeout: _, mcpMock, mcpConfigFile, mcpMockApprovalRules: ________, agent: __, debug: ___, transport: _____, mcpSafety: ______, opencodeExecutable, ...rest } = opts;
+    const { timeout: _, mcpMock, mcpScenario: _________, mcpConfigFile, mcpMockApprovalRules: ________, agent: __, debug: ___, transport: _____, mcpSafety: ______, opencodeExecutable, ...rest } = opts;
     const workspace = await prepareWorkspace({
         ...rest,
         agent: agentName,
@@ -471,6 +516,8 @@ export async function createAgent(opts) {
         opencodeExecutable,
         opencodeMcpToolNames: agentName === 'opencode' ? collectOpenCodeMcpToolNames(mcpMock) : undefined,
         scriptedMcp,
+        scenarioArtifact,
+        scenarioRuntimeFactory,
         sensitiveValues: workspace.sensitiveValues ?? collectSensitiveEnvValues(workspace.env),
     });
     lifecycleCore.registerAgent(agent);

package/dist/sdk/evaluate.js

@@ -42,6 +42,7 @@ function makeEvaluateAgent() {
             toolEvents,
             runCommand: (cmd) => agent.exec(cmd),
             artifacts: createSessionArtifacts(agent.workspace, toolEvents),
+            scenarioEvidence: agent.scenarioEvidence,
         };
         const trackedLLM = opts?.llm ?? agent.llm;
         // Snapshot conversation tokens BEFORE running scorers, for first-eval attribution.
@@ -80,7 +81,7 @@ function makeEvaluateAgent() {
             ...(opts?.evaluationDefinitionKey
                 ? { evaluationDefinitionKey: opts.evaluationDefinitionKey }
                 : {}),
-            trial: buildTrialResult(agent.log, { ...evalResult, tokenUsage: deltaTokenUsage }, conversationTokens, conversationCost),
+            trial: buildTrialResult(agent.log, { ...evalResult, tokenUsage: deltaTokenUsage }, agent.scenarioEvidence, conversationTokens, conversationCost),
         };
         emitEvalResult({ result: recordedResult, agent });
         maybeThrowOnScorerErrors(recordedResult, opts?.onScorerError ?? 'skip');
@@ -110,6 +111,7 @@ async function fromSnapshot(snapshotPath, scorers, opts) {
             return sandboxExec(cmd, { cwd: workspace, env: getProcessEnv() });
         },
         artifacts: createSessionArtifacts(snapshot.workspace ?? '', snapshot.toolEvents),
+        scenarioEvidence: snapshot.scenarioEvidence ?? [],
     };
     const scoringStartedAt = performance.now();
     const evalResult = await evaluateWithContext(ctx, scorers, { ...opts, llm: trackedLLM });
@@ -121,7 +123,7 @@ async function fromSnapshot(snapshotPath, scorers, opts) {
         ...(opts?.evaluationDefinitionKey
             ? { evaluationDefinitionKey: opts.evaluationDefinitionKey }
             : {}),
-        trial: buildTrialResult(snapshot.log, evalResult),
+        trial: buildTrialResult(snapshot.log, evalResult, snapshot.scenarioEvidence),
     };
     maybeThrowOnScorerErrors(recordedResult, opts?.onScorerError ?? 'skip');
     return recordedResult;
@@ -265,7 +267,7 @@ function matchesArtifactPattern(artifactPath, pattern) {
         return artifactPath.includes(pattern);
     return pattern.test(artifactPath);
 }
-function buildTrialResult(log, result, conversationTokens, conversationCost) {
+function buildTrialResult(log, result, scenarioEvidence, conversationTokens, conversationCost) {
     const nCommands = log.filter((entry) => entry.type === 'command').length;
     const skills = extractSkillsFromLog(log);
     return {
@@ -285,6 +287,7 @@ function buildTrialResult(log, result, conversationTokens, conversationCost) {
         // field.
         ...conversationCost,
         session_log: [...log],
+        ...(scenarioEvidence && scenarioEvidence.length > 0 ? { scenario_evidence: structuredClone(scenarioEvidence) } : {}),
         ...(skills.length > 0 ? { skills_used: skills } : {}),
     };
 }

package/dist/sdk/index.d.ts

@@ -2,8 +2,12 @@ export { createAgent } from './agent.js';
 export { resolveAgentName, resolveCodexTransport, InvalidTransportEnvError, } from './agent-resolution.js';
 export { AgentCrashError } from './agent-crash.js';
 export { check, score, judge, toolUsage } from './scorers.js';
+export { compileScenario, compileScenarioText } from './scenario-machine-v2.js';
+export { findScenarioCaseMatches, getFinalScenarioState, getScenarioStateTimeline, ScenarioEvidenceError, wasScenarioCaseMatched, } from './scenario-evidence.js';
 export { getMcpToolCall, isMcpToolCall, findMcpToolCalls, getMcpStartupStatus, isMcpStartupStatus, getMcpApproval, isMcpApproval, findMcpApprovals, getMcpInvocation, wasMcpToolInvoked, } from './mcp-evidence.js';
 export type { McpMockApprovalRule, McpMockJsonValue } from './mcp-mock-approvals.js';
+export type { CompileScenarioResult, EvidenceEnvelope, JsonObject, JsonPrimitive, JsonValue, MatchExpr, MatchPredicate, McpContent, ScenarioArtifact, ScenarioCase, ScenarioDiagnostic, ScenarioEvidence, ScenarioMachineV2, ScenarioRejection, ScenarioSuccess, ScenarioToolError, } from './scenario-machine-v2.js';
+export type { ExpectedScenarioCaseMatch, ScenarioCaseMatchEvidence, ScenarioStateTransitionEvidence, } from './scenario-evidence.js';
 export { decideMcpToolCall, redactMcpSecrets, } from './mcp-safety.js';
 export { evaluate, EvalScorerError } from './evaluate.js';
 export { RUN_SNAPSHOT_VERSION, buildRunSnapshot, loadRunSnapshot, SnapshotParseError, SnapshotVersionError, WorkspaceMissingError, } from './snapshots.js';

package/dist/sdk/index.js

@@ -3,6 +3,8 @@ export { createAgent } from './agent.js';
 export { resolveAgentName, resolveCodexTransport, InvalidTransportEnvError, } from './agent-resolution.js';
 export { AgentCrashError } from './agent-crash.js';
 export { check, score, judge, toolUsage } from './scorers.js';
+export { compileScenario, compileScenarioText } from './scenario-machine-v2.js';
+export { findScenarioCaseMatches, getFinalScenarioState, getScenarioStateTimeline, ScenarioEvidenceError, wasScenarioCaseMatched, } from './scenario-evidence.js';
 export { getMcpToolCall, isMcpToolCall, findMcpToolCalls, getMcpStartupStatus, isMcpStartupStatus, getMcpApproval, isMcpApproval, findMcpApprovals, getMcpInvocation, wasMcpToolInvoked, } from './mcp-evidence.js';
 export { decideMcpToolCall, redactMcpSecrets, } from './mcp-safety.js';
 export { evaluate, EvalScorerError } from './evaluate.js';

package/dist/sdk/managed-session.d.ts

@@ -5,6 +5,8 @@ import type { McpSafetyOptions } from './mcp-safety.js';
 import type { LLMPort } from '../utils/llm-types.js';
 import type { AskBus } from './ask-bus/types.js';
 import type { CompiledMcpMockSession } from './mcp-mock-approvals.js';
+import { type PublicScenarioRuntimeFactory } from '../internal/direct-mcp-v2/public-scenario-runtime.js';
+import type { EvidenceEnvelope, ScenarioArtifact } from '../internal/direct-mcp-v2/types.js';
 export interface ManagedSessionDeps {
     ws: Workspace;
     agentName: AgentName;
@@ -36,6 +38,10 @@ export interface ManagedSessionDeps {
     opencodeMcpToolNames?: string[];
     /** Trusted pre-workspace compiled generated-MCP declaration. */
     scriptedMcp?: CompiledMcpMockSession;
+    scenarioArtifact?: ScenarioArtifact;
+    /** Provider adapter entrypoint; defaults to the preserved Claude bridge. */
+    scenarioRuntimeFactory?: PublicScenarioRuntimeFactory;
+    onScenarioEvidence?: (evidence: readonly EvidenceEnvelope[]) => void;
     /** Runtime-only values that must not enter session logs or persisted results. */
     sensitiveValues?: readonly string[];
 }

package/dist/sdk/managed-session.js

@@ -10,6 +10,8 @@ import { attachTurnResultSensitiveValues, cloneTurnResultWithSensitiveValues, ge
 import { attachToolEventSensitiveValues, getToolEventSensitiveValues } from './tool-event-secrets.js';
 import { sanitizePersistenceValue } from '../tool-event-results.js';
 import { startScriptedMcpMockHost, } from '../providers/scripted-mcp-mock-host.js';
+import { startPublicClaudeScenarioRuntime, } from '../internal/direct-mcp-v2/public-scenario-runtime.js';
+import { TrialExecutionError } from '../internal/direct-mcp-v2/cleanup.js';
 export function createManagedSession(deps) {
     const { ws, agentName, timeoutSec, messages, log, model, conversationWindow, llm } = deps;
     const agentTimeoutMs = timeoutSec * 1000;
@@ -40,9 +42,12 @@ export function createManagedSession(deps) {
     let setupDone = false;
     let currentSignal;
     let scriptedHost;
+    let scenarioRuntime;
     let activeTurn = false;
     let nextTurnNumber = 0;
     let disposePromise;
+    let primaryTurnError;
+    let inFlightTurn;
     const runCommand = async (cmd) => {
         const result = await ws.exec(cmd, { signal: currentSignal });
         log.push(sanitizePersistenceValue({
@@ -62,67 +67,145 @@ export function createManagedSession(deps) {
         if (remaining <= 0)
             throw new Error(`${label} timed out`);
         activeTurn = true;
+        let finishTurnJoin;
+        const turnJoin = new Promise((resolve) => { finishTurnJoin = resolve; });
+        inFlightTurn = turnJoin;
         try {
             return await withAbortTimeout(async (signal) => {
-                currentSignal = signal;
-                if (!session) {
-                    // Run auth setup commands before first agent turn
-                    if (!setupDone) {
-                        for (const cmd of ws.setupCommands) {
-                            await ws.exec(cmd, { signal });
-                            signal.throwIfAborted();
+                try {
+                    currentSignal = signal;
+                    if (!session) {
+                        // Run auth setup commands before first agent turn
+                        if (!setupDone) {
+                            for (const cmd of ws.setupCommands) {
+                                await ws.exec(cmd, { signal });
+                                signal.throwIfAborted();
+                            }
+                            setupDone = true;
+                        }
+                        // Carry the workspace's resolved env (from `prepareWorkspace
+                        // → resolveCredentials`) into the runtime handle so drivers
+                        // that auth through `Options.env` (notably the Claude SDK
+                        // driver) can lift Anthropic keys out. Drivers that only
+                        // need the workspace path keep using `getWorkspacePath`.
+                        const runtime = {
+                            handle: ws.path,
+                            workspacePath: ws.path,
+                            env: ws.env,
+                        };
+                        if (deps.scriptedMcp) {
+                            scriptedHost = await startScriptedMcpMockHost(deps.scriptedMcp);
+                            sessionOptions.scriptedMcpHost = scriptedHost;
+                        }
+                        if (deps.scenarioArtifact) {
+                            const startScenarioRuntime = deps.scenarioRuntimeFactory ?? startPublicClaudeScenarioRuntime;
+                            scenarioRuntime = await startScenarioRuntime({
+                                artifact: deps.scenarioArtifact,
+                                workspacePath: ws.path,
+                                environment: ws.env,
+                                onEvidence: deps.onScenarioEvidence,
+                            });
+                            try {
+                                scenarioRuntime.configureSession(sessionOptions);
+                            }
+                            catch (error) {
+                                try {
+                                    await scenarioRuntime.dispose();
+                                }
+                                catch (cleanupError) {
+                                    throw new AggregateError([error, cleanupError], 'Scenario provider projection failed and coordinator cleanup also failed');
+                                }
+                                scenarioRuntime = undefined;
+                                throw error;
+                            }
+                        }
+                        try {
+                            session = await createAgentSession(agent, runtime, runCommand, sessionOptions);
+                        }
+                        catch (error) {
+                            try {
+                                await scriptedHost?.dispose();
+                                await scenarioRuntime?.dispose();
+                            }
+                            catch (cleanupError) {
+                                throw new AggregateError([error, cleanupError], 'Agent session setup failed and scenario cleanup also failed');
+                            }
+                            scriptedHost = undefined;
+                            scenarioRuntime = undefined;
+                            throw error;
                         }
-                        setupDone = true;
-                    }
-                    // Carry the workspace's resolved env (from `prepareWorkspace
-                    // → resolveCredentials`) into the runtime handle so drivers
-                    // that auth through `Options.env` (notably the Claude SDK
-                    // driver) can lift Anthropic keys out. Drivers that only
-                    // need the workspace path keep using `getWorkspacePath`.
-                    const runtime = {
-                        handle: ws.path,
-                        workspacePath: ws.path,
-                        env: ws.env,
-                    };
-                    if (deps.scriptedMcp) {
-                        scriptedHost = await startScriptedMcpMockHost(deps.scriptedMcp);
-                        sessionOptions.scriptedMcpHost = scriptedHost;
                     }
+                    const turnNumber = ++nextTurnNumber;
+                    scriptedHost?.beginTurn(turnNumber);
+                    scenarioRuntime?.beginTurn(`turn-${turnNumber}`, signal);
+                    let result;
                     try {
-                        session = await createAgentSession(agent, runtime, runCommand, sessionOptions);
+                        result = turnNumber === 1
+                            ? await session.start({ message })
+                            : await session.reply({ message });
                     }
                     catch (error) {
-                        await scriptedHost?.dispose();
-                        scriptedHost = undefined;
+                        try {
+                            await scenarioRuntime?.failTurn(error);
+                        }
+                        catch (lifecycleError) {
+                            if (lifecycleError instanceof TrialExecutionError) {
+                                primaryTurnError = lifecycleError;
+                                throw lifecycleError;
+                            }
+                            const combined = new AggregateError([error, lifecycleError], 'Provider turn failed and scenario settlement also failed');
+                            primaryTurnError = combined;
+                            throw combined;
+                        }
+                        primaryTurnError = error;
                         throw error;
                     }
-                }
-                const turnNumber = ++nextTurnNumber;
-                scriptedHost?.beginTurn(turnNumber);
-                let result = turnNumber === 1
-                    ? await session.start({ message })
-                    : await session.reply({ message });
-                if (scriptedHost) {
-                    const settled = scriptedHost.settleEvents(result.toolEvents);
-                    result.toolEvents = settled.events;
-                    if (settled.error) {
-                        result = cloneTurnResultWithSensitiveValues(result, {
-                            exitCode: 1,
-                            rawOutput: settled.error.message,
-                        });
+                    if (result.exitCode !== 0 || result.timedOut) {
+                        const providerTerminalError = new Error(`Provider terminal: exit ${result.exitCode}`);
+                        primaryTurnError = providerTerminalError;
+                        try {
+                            await scenarioRuntime?.failTurn(providerTerminalError);
+                        }
+                        catch (lifecycleError) {
+                            if (lifecycleError instanceof TrialExecutionError) {
+                                primaryTurnError = lifecycleError;
+                                throw lifecycleError;
+                            }
+                            const combined = new AggregateError([providerTerminalError, lifecycleError], 'Provider terminal failed and scenario settlement also failed');
+                            primaryTurnError = combined;
+                            throw combined;
+                        }
+                    }
+                    else {
+                        await scenarioRuntime?.settleTurn();
+                    }
+                    if (scriptedHost) {
+                        const settled = scriptedHost.settleEvents(result.toolEvents);
+                        result.toolEvents = settled.events;
+                        if (settled.error) {
+                            result = cloneTurnResultWithSensitiveValues(result, {
+                                exitCode: 1,
+                                rawOutput: settled.error.message,
+                            });
+                        }
+                    }
+                    const sensitiveValues = [...new Set([
+                            ...(deps.sensitiveValues ?? []),
+                            ...getTurnResultSensitiveValues(result),
+                        ])];
+                    for (const event of result.toolEvents) {
+                        attachToolEventSensitiveValues(event, [...new Set([
+                                ...sensitiveValues,
+                                ...getToolEventSensitiveValues(event),
+                            ])]);
                     }
+                    return attachTurnResultSensitiveValues(result, sensitiveValues);
                 }
-                const sensitiveValues = [...new Set([
-                        ...(deps.sensitiveValues ?? []),
-                        ...getTurnResultSensitiveValues(result),
-                    ])];
-                for (const event of result.toolEvents) {
-                    attachToolEventSensitiveValues(event, [...new Set([
-                            ...sensitiveValues,
-                            ...getToolEventSensitiveValues(event),
-                        ])]);
+                finally {
+                    finishTurnJoin();
+                    if (inFlightTurn === turnJoin)
+                        inFlightTurn = undefined;
                 }
-                return attachTurnResultSensitiveValues(result, sensitiveValues);
             }, remaining, label);
         }
         finally {
@@ -166,12 +249,36 @@ export function createManagedSession(deps) {
             if (disposePromise)
                 return disposePromise;
             disposePromise = (async () => {
+                const cleanupErrors = [];
                 try {
                     await session?.dispose?.();
                 }
-                finally {
+                catch (error) {
+                    cleanupErrors.push(error);
+                }
+                if (inFlightTurn) {
+                    try {
+                        await withAbortTimeout(async () => inFlightTurn, Math.min(agentTimeoutMs, 2_000), 'Agent turn cleanup');
+                    }
+                    catch (error) {
+                        cleanupErrors.push(error);
+                    }
+                }
+                try {
                     await scriptedHost?.dispose();
                 }
+                catch (error) {
+                    cleanupErrors.push(error);
+                }
+                try {
+                    await scenarioRuntime?.dispose();
+                }
+                catch (error) {
+                    cleanupErrors.push(error);
+                }
+                if (cleanupErrors.length > 0) {
+                    throw new AggregateError(primaryTurnError === undefined ? cleanupErrors : [primaryTurnError, ...cleanupErrors], primaryTurnError === undefined ? 'Agent session cleanup failed' : 'Provider turn failed and cleanup also failed');
+                }
             })();
             return disposePromise;
         },

package/dist/sdk/scenario-evidence.d.ts

@@ -0,0 +1,27 @@
+import type { EvidenceEnvelope } from '../internal/direct-mcp-v2/types.js';
+export type ExpectedScenarioCaseMatch = {
+    caseId?: string;
+    serverId?: string;
+    toolId?: string;
+    turnId?: string;
+};
+export type ScenarioCaseMatchEvidence = {
+    trialId: string;
+    turnId: string;
+    invocationId: string;
+    serverId: string;
+    toolId: string;
+    caseId: string;
+    stateBefore: string;
+};
+export type ScenarioStateTransitionEvidence = ScenarioCaseMatchEvidence & {
+    stateAfter: string;
+    committedEpoch: number;
+};
+export declare class ScenarioEvidenceError extends Error {
+    constructor(message: string);
+}
+export declare function findScenarioCaseMatches(evidence: readonly EvidenceEnvelope[], expected?: ExpectedScenarioCaseMatch): ScenarioCaseMatchEvidence[];
+export declare function wasScenarioCaseMatched(evidence: readonly EvidenceEnvelope[], expected: ExpectedScenarioCaseMatch): boolean;
+export declare function getScenarioStateTimeline(evidence: readonly EvidenceEnvelope[]): ScenarioStateTransitionEvidence[];
+export declare function getFinalScenarioState(evidence: readonly EvidenceEnvelope[]): string;

package/dist/sdk/scenario-evidence.js

@@ -0,0 +1,94 @@
+import { verifyEvidenceChain } from '../internal/direct-mcp-v2/evidence.js';
+export class ScenarioEvidenceError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ScenarioEvidenceError';
+    }
+}
+export function findScenarioCaseMatches(evidence, expected = {}) {
+    const invocations = canonicalInvocations(evidence);
+    const matches = [];
+    for (const envelope of evidence) {
+        const decision = envelope.payload;
+        if (decision.type !== 'mcp.decision' || decision.outcome !== 'matched' || !decision.caseId)
+            continue;
+        const invocation = invocations.get(decision.invocationId);
+        if (!invocation)
+            throw new ScenarioEvidenceError(`matched decision references unknown invocation ${decision.invocationId}`);
+        const match = { ...invocation, caseId: decision.caseId };
+        if (matchesExpectedCase(match, expected))
+            matches.push(match);
+    }
+    return matches;
+}
+export function wasScenarioCaseMatched(evidence, expected) {
+    return findScenarioCaseMatches(evidence, expected).length > 0;
+}
+export function getScenarioStateTimeline(evidence) {
+    const matches = new Map(findScenarioCaseMatches(evidence).map((entry) => [entry.invocationId, entry]));
+    const timeline = [];
+    for (const envelope of evidence) {
+        const commit = envelope.payload;
+        if (commit.type !== 'mcp.commit')
+            continue;
+        const match = matches.get(commit.invocationId);
+        if (!match)
+            throw new ScenarioEvidenceError(`commit references unmatched invocation ${commit.invocationId}`);
+        if (match.stateBefore !== commit.stateBefore) {
+            throw new ScenarioEvidenceError(`commit state disagrees with invocation ${commit.invocationId}`);
+        }
+        timeline.push({
+            ...match,
+            stateAfter: commit.stateAfter,
+            committedEpoch: commit.committedEpoch,
+        });
+    }
+    return timeline;
+}
+export function getFinalScenarioState(evidence) {
+    assertCanonicalEvidence(evidence);
+    const payload = evidence.at(-1)?.payload;
+    if (payload?.type === 'turn.finalized' && payload.state !== undefined)
+        return payload.state;
+    throw new ScenarioEvidenceError('canonical evidence does not end with a finalized scenario state');
+}
+function canonicalInvocations(evidence) {
+    assertCanonicalEvidence(evidence);
+    const invocations = new Map();
+    for (const envelope of evidence) {
+        const invocation = envelope.payload;
+        if (invocation.type !== 'mcp.invocation')
+            continue;
+        if (invocations.has(invocation.invocationId)) {
+            throw new ScenarioEvidenceError(`duplicate invocation ${invocation.invocationId}`);
+        }
+        invocations.set(invocation.invocationId, {
+            trialId: envelope.trialId,
+            turnId: envelope.turnId,
+            invocationId: invocation.invocationId,
+            serverId: invocation.serverId,
+            toolId: invocation.toolId,
+            stateBefore: invocation.stateBefore,
+        });
+    }
+    return invocations;
+}
+function assertCanonicalEvidence(evidence) {
+    const first = evidence[0];
+    if (!first)
+        throw new ScenarioEvidenceError('canonical evidence is empty');
+    const chain = verifyEvidenceChain(evidence, first.artifactDigest);
+    if (!chain.ok)
+        throw new ScenarioEvidenceError(`canonical evidence chain failed at index ${chain.index}: ${chain.reason}`);
+    for (const [index, envelope] of evidence.entries()) {
+        if (envelope.trialId !== first.trialId) {
+            throw new ScenarioEvidenceError(`canonical evidence changes trialId at index ${index}`);
+        }
+    }
+}
+function matchesExpectedCase(match, expected) {
+    return (expected.caseId === undefined || match.caseId === expected.caseId)
+        && (expected.serverId === undefined || match.serverId === expected.serverId)
+        && (expected.toolId === undefined || match.toolId === expected.toolId)
+        && (expected.turnId === undefined || match.turnId === expected.turnId);
+}

package/dist/sdk/scenario-machine-v2.d.ts

@@ -0,0 +1,9 @@
+import type { CompileScenarioResult } from '../internal/direct-mcp-v2/compiler.js';
+import type { ScenarioMachineV2 as InternalScenarioMachineV2 } from '../internal/direct-mcp-v2/types.js';
+/** Compile the public V2 source contract, whose concurrency safety policy is fixed by the version. */
+export declare function compileScenario(source: unknown): CompileScenarioResult;
+/** Compile strict JSON text using the public V2 source contract. */
+export declare function compileScenarioText(text: string): CompileScenarioResult;
+export type { CompileScenarioResult } from '../internal/direct-mcp-v2/compiler.js';
+export type ScenarioMachineV2 = Pick<InternalScenarioMachineV2, 'version' | 'scenarioId' | 'initialState' | 'servers' | 'states'>;
+export type { EvidenceEnvelope, JsonObject, JsonPrimitive, JsonValue, MatchExpr, MatchPredicate, McpContent, ScenarioArtifact, ScenarioCase, ScenarioDiagnostic, ScenarioEvidence, ScenarioRejection, ScenarioSuccess, ScenarioToolError, } from '../internal/direct-mcp-v2/types.js';

package/dist/sdk/scenario-machine-v2.js

@@ -0,0 +1,37 @@
+import { compileScenario as compileInternalScenario } from '../internal/direct-mcp-v2/compiler.js';
+import { canonicalJson, parseStrictJson } from '../internal/direct-mcp-v2/json.js';
+const V2_CONCURRENCY_POLICY = 'poison-effectful-overlap';
+function object(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/** Compile the public V2 source contract, whose concurrency safety policy is fixed by the version. */
+export function compileScenario(source) {
+    try {
+        canonicalJson(source);
+    }
+    catch (error) {
+        return { ok: false, diagnostics: [{ code: 'INVALID_JSON_VALUE', path: '$', message: error instanceof Error ? error.message : String(error) }] };
+    }
+    if (!object(source))
+        return compileInternalScenario(source);
+    const suppliedConcurrency = Object.prototype.hasOwnProperty.call(source, 'concurrency');
+    const compiled = compileInternalScenario({ ...source, concurrency: V2_CONCURRENCY_POLICY });
+    if (!suppliedConcurrency)
+        return compiled;
+    const diagnostic = { code: 'UNKNOWN_FIELD', path: '$/concurrency', message: 'unknown field concurrency' };
+    if (compiled.ok)
+        return { ok: false, diagnostics: [diagnostic] };
+    return {
+        ok: false,
+        diagnostics: [...compiled.diagnostics, diagnostic].sort((left, right) => canonicalJson(left).localeCompare(canonicalJson(right), 'en')),
+    };
+}
+/** Compile strict JSON text using the public V2 source contract. */
+export function compileScenarioText(text) {
+    try {
+        return compileScenario(parseStrictJson(text));
+    }
+    catch (error) {
+        return { ok: false, diagnostics: [{ code: 'INVALID_JSON_TEXT', path: '$', message: error instanceof Error ? error.message : String(error) }] };
+    }
+}