@replayci/replay 0.1.13 → 0.1.15

package/dist/index.cjs

@@ -2320,7 +2320,6 @@ function normalizeInlineContract(input) {
   if (!tool) {
     throw new ReplayConfigurationError("Inline contract is missing required field: tool");
   }
-  const assertions = toRecord5(source.assertions);
   const expectTools = toStringArray(source.expect_tools);
   const expectedToolCalls = toExpectedToolCalls(source.expected_tool_calls);
   const contract = {
@@ -2328,28 +2327,38 @@ function normalizeInlineContract(input) {
     ...toString5(source.tool_schema_hash) ? { tool_schema_hash: toString5(source.tool_schema_hash) } : {},
     ...isSideEffect(source.side_effect) ? { side_effect: source.side_effect } : {},
     ...toString5(source.contract_file) ? { contract_file: toString5(source.contract_file) } : {},
-    timeouts: {
-      total_ms: toNonNegativeNumber(toRecord5(source.timeouts).total_ms, 0)
-    },
-    retries: {
-      max_attempts: Math.max(1, toNonNegativeNumber(toRecord5(source.retries).max_attempts, 1)),
-      retry_on: toStringArray(toRecord5(source.retries).retry_on)
-    },
-    rate_limits: {
-      on_429: {
-        respect_retry_after: toBoolean(toRecord5(toRecord5(source.rate_limits).on_429).respect_retry_after, false),
-        max_sleep_seconds: toNonNegativeNumber(
-          toRecord5(toRecord5(source.rate_limits).on_429).max_sleep_seconds,
-          0
-        )
+    ...source.timeouts != null ? {
+      timeouts: { total_ms: toNonNegativeNumber(toRecord5(source.timeouts).total_ms, 0) }
+    } : {},
+    ...source.retries != null ? {
+      retries: {
+        max_attempts: Math.max(1, toNonNegativeNumber(toRecord5(source.retries).max_attempts, 1)),
+        retry_on: toStringArray(toRecord5(source.retries).retry_on)
       }
-    },
-    assertions: {
-      input_invariants: toInvariantArray(assertions.input_invariants),
-      output_invariants: toInvariantArray(assertions.output_invariants)
-    },
-    golden_cases: Array.isArray(source.golden_cases) ? source.golden_cases : [],
-    allowed_errors: toStringArray(source.allowed_errors),
+    } : {},
+    ...source.rate_limits != null ? {
+      rate_limits: {
+        on_429: {
+          respect_retry_after: toBoolean(toRecord5(toRecord5(source.rate_limits).on_429).respect_retry_after, false),
+          max_sleep_seconds: toNonNegativeNumber(
+            toRecord5(toRecord5(source.rate_limits).on_429).max_sleep_seconds,
+            0
+          )
+        }
+      }
+    } : {},
+    ...source.assertions != null ? {
+      assertions: {
+        input_invariants: toInvariantArray(toRecord5(source.assertions).input_invariants),
+        output_invariants: toInvariantArray(toRecord5(source.assertions).output_invariants)
+      }
+    } : {},
+    ...source.golden_cases != null ? {
+      golden_cases: Array.isArray(source.golden_cases) ? source.golden_cases : []
+    } : {},
+    ...source.allowed_errors != null ? {
+      allowed_errors: toStringArray(source.allowed_errors)
+    } : {},
     ...expectTools.length > 0 ? { expect_tools: expectTools } : {},
     ...toToolOrder(source.tool_order, expectTools.length > 0) ? {
       tool_order: toToolOrder(source.tool_order, expectTools.length > 0)
@@ -2375,8 +2384,9 @@ function normalizeInlineContract(input) {
     ...Array.isArray(source.schema_derived_exclude) ? { schema_derived_exclude: source.schema_derived_exclude } : {},
     ...Array.isArray(source.binds) ? { binds: source.binds } : {}
   };
-  validateSafeRegexes(contract);
-  return contract;
+  const filled = { ...(0, import_contracts_core2.fillContractDefaults)(contract), ...contract.contract_file ? { contract_file: contract.contract_file } : {} };
+  validateSafeRegexes(filled);
+  return filled;
 }
 function validateContractSet(contracts) {
   const seenKeys = /* @__PURE__ */ new Set();
@@ -2395,11 +2405,11 @@ function validateSafeRegexes(contract) {
   const invariantGroups = [
     {
       label: "assertions.input_invariants",
-      invariants: contract.assertions.input_invariants
+      invariants: contract.assertions?.input_invariants ?? []
     },
     {
       label: "assertions.output_invariants",
-      invariants: contract.assertions.output_invariants
+      invariants: contract.assertions?.output_invariants ?? []
     }
   ];
   for (const [index, expectedToolCall] of (contract.expected_tool_calls ?? []).entries()) {
@@ -3002,7 +3012,7 @@ function evaluateExpectTools(contract, toolCalls) {
 function evaluateOutputInvariants(contract, normalizedResponse) {
   const invariantFailures = (0, import_contracts_core3.evaluateInvariants)(
     normalizedResponse,
-    contract.assertions.output_invariants,
+    contract.assertions?.output_invariants ?? [],
     process.env
   );
   return invariantFailures.map(
@@ -3052,7 +3062,7 @@ function evaluateArgumentInvariants(contract, toolCalls) {
   return failures;
 }
 function mapInvariantFailure(contract, failure, normalizedResponse) {
-  const invariant = findMatchingInvariant(contract.assertions.output_invariants, failure);
+  const invariant = findMatchingInvariant(contract.assertions?.output_invariants ?? [], failure);
   const lookup = (0, import_contracts_core3.getPathValue)(normalizedResponse, failure.path);
   return {
     path: failure.path,
@@ -3778,7 +3788,7 @@ function createInitialState(sessionId, options) {
     checkpointCount: 0
   };
 }
-function finalizeExecutedStep(state, step, contracts, compiledSession) {
+function finalizeExecutedStep(state, step, contracts, compiledSession, options) {
   const newSteps = [...state.steps, step];
   const newToolCallCounts = updateToolCallCounts(state.toolCallCounts, step);
   const resolvedContracts = compiledSession ? Array.from(compiledSession.perToolContracts.values()) : contracts;
@@ -3788,7 +3798,7 @@ function finalizeExecutedStep(state, step, contracts, compiledSession) {
     step
   );
   const costDelta = computeStepCost(step);
-  const newPhase = compiledSession ? recomputePhaseFromCommitted(step.toolCalls, state, compiledSession) : state.currentPhase;
+  const newPhase = options?.deferPhase ? state.currentPhase : compiledSession ? recomputePhaseFromCommitted(step.toolCalls, state, compiledSession) : state.currentPhase;
   return {
     ...state,
     steps: newSteps,
@@ -4634,7 +4644,7 @@ function validateToolResultMessages(messages, contracts, provider) {
   for (const result of toolResults) {
     const contract = contractByTool.get(result.toolName);
     if (!contract) continue;
-    const outputInvariants = contract.assertions.output_invariants;
+    const outputInvariants = contract.assertions?.output_invariants ?? [];
     if (outputInvariants.length === 0) continue;
     let parsed;
     try {
@@ -5284,6 +5294,32 @@ var RuntimeClient = class {
       stateVersion: h.state_version
     };
   }
+  /**
+   * Fetch governance plan for an agent.
+   * Returns null on 404 (no plan exists).
+   * @see zero-config-governance.md § GET /api/v1/governance/plan
+   */
+  async fetchGovernancePlan(agent, environment) {
+    const env = environment ?? "development";
+    try {
+      const data = await this.get(
+        `/api/v1/governance/plan?agent=${encodeURIComponent(agent)}&environment=${encodeURIComponent(env)}`
+      );
+      return {
+        status: data.status,
+        compiledSession: data.compiled_session,
+        compiledHash: data.compiled_hash,
+        observations: data.observations,
+        confidence: data.confidence,
+        version: data.version
+      };
+    } catch (err) {
+      if (err instanceof RuntimeClientError && err.httpStatus === 404) {
+        return null;
+      }
+      throw err;
+    }
+  }
   getHealth() {
     return {
       circuitOpen: this.now() < this.circuitOpenUntil,
@@ -5450,9 +5486,14 @@ function replay(client, opts = {}) {
     return createInactiveSession(client, sessionId, "Client already has an active observe() or replay() attachment");
   }
   let contracts;
+  let zeroConfigMode = false;
   try {
     contracts = resolveContracts(opts);
   } catch (err) {
+    const apiKeyForGov = resolveApiKey2(opts);
+    if (apiKeyForGov && !opts.contracts && !opts.contractsDir) {
+      return createGovernanceSession(client, sessionId, agent, provider, apiKeyForGov, opts, diagnostics);
+    }
     const detail = err instanceof Error ? err.message : "Failed to load contracts";
     emitDiagnostic2(diagnostics, { type: "replay_compile_error", details: detail });
     return createBlockingInactiveSession(client, sessionId, detail);
@@ -5659,6 +5700,8 @@ function replay(client, opts = {}) {
   let shadowEvaluationCount = 0;
   let manualFilter = null;
   const deferredReceipts = /* @__PURE__ */ new Map();
+  let deferredPhase = null;
+  const hasWrappedTools = opts.tools != null && Object.keys(opts.tools).length > 0;
   const contractLimits = resolveSessionLimits(contracts);
   const compiledLimits = compiledSession?.sessionLimits;
   const mergedLimits = { ...contractLimits ?? {}, ...compiledLimits ?? {} };
@@ -5795,6 +5838,7 @@ function replay(client, opts = {}) {
       total_ms: 0,
       enforcement_ms: 0
     };
+    deferredPhase = null;
     const trace = createTrace(sessionState.totalStepCount);
     const traceCtx = { trace };
     let currentTraceStage = "narrow";
@@ -6617,9 +6661,29 @@ function replay(client, opts = {}) {
                 }
               }
             }
+            const compatHasPhaseTransition = !!(phaseResult?.legal && phaseResult.newPhase !== sessionState.currentPhase);
+            const compatShouldDefer = hasWrappedTools && compatHasPhaseTransition;
             const prevVersion = sessionState.stateVersion;
-            sessionState = finalizeExecutedStep(sessionState, completedStep, contracts, compiledSession);
+            sessionState = finalizeExecutedStep(
+              sessionState,
+              completedStep,
+              contracts,
+              compiledSession,
+              compatShouldDefer ? { deferPhase: true } : void 0
+            );
             syncStateToStore(prevVersion, sessionState);
+            if (compatShouldDefer && compiledSession && phaseResult) {
+              const advancingTools = /* @__PURE__ */ new Set();
+              for (const tc of toolCalls) {
+                const contract = compiledSession.perToolContracts.get(tc.name);
+                if (contract?.transitions?.advances_to === phaseResult.newPhase) {
+                  advancingTools.add(tc.name);
+                }
+              }
+              if (advancingTools.size > 0 && phaseResult.newPhase != null) {
+                deferredPhase = { newPhase: phaseResult.newPhase, toolNames: advancingTools };
+              }
+            }
           }
           if (advisoryDecision.action === "block") {
             sessionState = recordDecisionOutcome(sessionState, "blocked");
@@ -6709,11 +6773,31 @@ function replay(client, opts = {}) {
               }
             }
           }
+          const hasPhaseTransition = phaseResult?.legal && phaseResult.newPhase !== sessionState.currentPhase;
+          const shouldDeferPhase = hasWrappedTools && !!hasPhaseTransition;
           const prevVersionAllow = sessionState.stateVersion;
-          sessionState = finalizeExecutedStep(sessionState, completedStep, contracts, compiledSession);
+          sessionState = finalizeExecutedStep(
+            sessionState,
+            completedStep,
+            contracts,
+            compiledSession,
+            shouldDeferPhase ? { deferPhase: true } : void 0
+          );
           sessionState = recordDecisionOutcome(sessionState, "allowed");
           syncStateToStore(prevVersionAllow, sessionState);
           timing.finalize_ms += Date.now() - enforceFinalizeStart;
+          if (shouldDeferPhase && compiledSession) {
+            const advancingTools = /* @__PURE__ */ new Set();
+            for (const tc of toolCalls) {
+              const contract = compiledSession.perToolContracts.get(tc.name);
+              if (contract?.transitions?.advances_to === phaseResult.newPhase) {
+                advancingTools.add(tc.name);
+              }
+            }
+            if (advancingTools.size > 0 && phaseResult.newPhase != null) {
+              deferredPhase = { newPhase: phaseResult.newPhase, toolNames: advancingTools };
+            }
+          }
           if (isActiveGovern && !attemptDegraded && attemptPendingCalls && attemptPendingCalls.size > 0) {
             for (const [toolCallId, pending] of attemptPendingCalls) {
               deferredReceipts.set(toolCallId, {
@@ -6731,8 +6815,8 @@ function replay(client, opts = {}) {
             checked: { gate_mode: gateMode },
             found: { blocked_count: 0, action: "allow" }
           });
-          const allowNewPhase = phaseResult && phaseResult.legal && phaseResult.newPhase !== sessionState.currentPhase ? phaseResult.newPhase : sessionState.currentPhase;
-          trace.push({ stage: "finalize", tool: null, verdict: "info", reason: "cycle_complete", checked: {}, found: { state_version: sessionState.stateVersion, phase_before: completedStep.phase, phase_after: allowNewPhase, tools_committed: toolCalls.map((tc) => tc.name), tools_blocked: [], killed: false, step_index: sessionState.totalStepCount } });
+          const allowNewPhase = phaseResult && phaseResult.legal && phaseResult.newPhase !== (completedStep.phase ?? sessionState.currentPhase) ? phaseResult.newPhase : sessionState.currentPhase;
+          trace.push({ stage: "finalize", tool: null, verdict: "info", reason: "cycle_complete", checked: {}, found: { state_version: sessionState.stateVersion, phase_before: completedStep.phase, phase_after: allowNewPhase, ...shouldDeferPhase ? { phase_deferred: true } : {}, tools_committed: toolCalls.map((tc) => tc.name), tools_blocked: [], killed: false, step_index: sessionState.totalStepCount } });
           trace.complete = true;
           lastTrace = trace;
           emitDiagnostic2(diagnostics, { type: "replay_trace", session_id: sessionId, trace });
@@ -7079,6 +7163,10 @@ function replay(client, opts = {}) {
           throw new ReplayKillError(sessionId, killedAt);
         }
         const result = await executor(args);
+        if (deferredPhase && deferredPhase.toolNames.has(toolName)) {
+          sessionState = { ...sessionState, currentPhase: deferredPhase.newPhase };
+          deferredPhase = null;
+        }
         if (runtimeClient && leaseFence && !runtimeDegraded) {
           for (const [callId, deferred] of deferredReceipts) {
             if (deferred.toolName === toolName) {
@@ -7329,7 +7417,7 @@ function validateResponse2(response, toolCalls, contracts, requestToolNames, unm
     }
   }
   for (const contract of matched) {
-    const outputInvariants = contract.assertions.output_invariants;
+    const outputInvariants = contract.assertions?.output_invariants ?? [];
     if (outputInvariants.length > 0) {
       const normalizedResponse = buildNormalizedResponse(response, toolCalls);
       const result = (0, import_contracts_core7.evaluateInvariants)(normalizedResponse, outputInvariants, process.env);
@@ -7497,8 +7585,9 @@ function evaluateInputInvariants(request, contracts) {
   const requestToolSet = new Set(requestToolNames);
   for (const contract of contracts) {
     if (!requestToolSet.has(contract.tool)) continue;
-    if (contract.assertions.input_invariants.length === 0) continue;
-    const result = (0, import_contracts_core7.evaluateInvariants)(request, contract.assertions.input_invariants, process.env);
+    const inputInvariants = contract.assertions?.input_invariants ?? [];
+    if (inputInvariants.length === 0) continue;
+    const result = (0, import_contracts_core7.evaluateInvariants)(request, inputInvariants, process.env);
     for (const failure of result) {
       failures.push({
         path: failure.path,
@@ -7873,6 +7962,126 @@ function createBlockingInactiveSession(client, sessionId, detail, configError) {
     handoff: () => Promise.resolve(null)
   };
 }
+function resolveGovernanceEnvironment(opts) {
+  if (opts.environment) return opts.environment;
+  const envVar = typeof process !== "undefined" ? process.env.REPLAYCI_ENVIRONMENT : void 0;
+  if (envVar === "staging") return "staging";
+  if (envVar === "production") return "production";
+  if (envVar === "development") return "development";
+  const nodeEnv = typeof process !== "undefined" ? process.env.NODE_ENV : void 0;
+  if (nodeEnv === "production") return "production";
+  return "development";
+}
+function governanceProtectionLevel(env) {
+  switch (env) {
+    case "production":
+      return "govern";
+    case "staging":
+      return "protect";
+    default:
+      return "monitor";
+  }
+}
+function createGovernanceSession(client, sessionId, agent, provider, apiKey, opts, diagnostics) {
+  const environment = resolveGovernanceEnvironment(opts);
+  const protLevel = governanceProtectionLevel(environment);
+  const runtimeClient = new RuntimeClient({
+    apiKey,
+    apiUrl: opts.runtimeUrl
+  });
+  let governancePlan;
+  let planFetchPromise = null;
+  let planFetchDone = false;
+  let planFetchError = null;
+  planFetchPromise = runtimeClient.fetchGovernancePlan(agent, environment).then((result) => {
+    governancePlan = result;
+    planFetchDone = true;
+  }).catch((err) => {
+    planFetchDone = true;
+    planFetchError = err instanceof Error ? err.message : String(err);
+    governancePlan = null;
+  });
+  const captureBuffer = new CaptureBuffer({
+    apiKey,
+    endpoint: opts.runtimeUrl
+  });
+  registerBeforeExit(captureBuffer);
+  const terminalInfo = resolveTerminal(client, provider);
+  if (!terminalInfo) {
+    emitDiagnostic2(diagnostics, { type: "replay_inactive", reason: "unsupported_client" });
+    return createInactiveSession(client, sessionId, "Could not resolve terminal resource");
+  }
+  const { terminal, originalCreate } = terminalInfo;
+  const patchedCreate = async function(...args) {
+    if (!planFetchDone && planFetchPromise) {
+      await planFetchPromise;
+    }
+    const hasApprovedPlan = governancePlan && (governancePlan.status === "approved" || governancePlan.status === "enforcing") && governancePlan.compiledSession;
+    if (hasApprovedPlan) {
+    }
+    const result = await originalCreate.apply(this, args);
+    try {
+      const toolCalls = extractToolCalls(result, provider);
+      const usage = extractUsage(result, provider);
+      const requestArg = args[0] && typeof args[0] === "object" ? args[0] : {};
+      captureBuffer.push({
+        schema_version: CAPTURE_SCHEMA_VERSION_CURRENT,
+        agent,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        provider,
+        model_id: requestArg.model ?? "unknown",
+        primary_tool_name: toolCalls[0]?.name ?? null,
+        tool_names: toolCalls.map((tc) => tc.name),
+        request: requestArg,
+        response: result,
+        usage,
+        latency_ms: 0,
+        sdk_session_id: sessionId
+      });
+    } catch {
+    }
+    return result;
+  };
+  terminal[terminalInfo.methodName] = patchedCreate;
+  setReplayAttached(client);
+  return {
+    client,
+    flush: () => captureBuffer.flush(),
+    restore() {
+      terminal[terminalInfo.methodName] = originalCreate;
+    },
+    kill() {
+    },
+    getHealth: () => ({
+      status: "healthy",
+      authorityState: "active",
+      protectionLevel: protLevel,
+      durability: "inactive",
+      tier: "compat",
+      compatEnforcement: "protective",
+      cluster_detected: false,
+      bypass_detected: false,
+      totalSteps: 0,
+      totalBlocks: 0,
+      totalErrors: 0,
+      killed: false,
+      shadowEvaluations: 0
+    }),
+    getState: () => EMPTY_STATE_SNAPSHOT,
+    getLastNarrowing: () => null,
+    getLastShadowDelta: () => null,
+    getLastTrace: () => null,
+    narrow() {
+    },
+    widen() {
+    },
+    addLabel() {
+    },
+    tools: {},
+    getWorkflowState: () => Promise.resolve(null),
+    handoff: () => Promise.resolve(null)
+  };
+}
 function toNarrowingSnapshot(result) {
   if (!result || result.removed.length === 0) return null;
   return {

package/dist/index.d.cts

@@ -587,6 +587,15 @@ type ReplayOptions = {
     runtimeUrl?: string;
     captureLevel?: CapturePrivacyTier;
     diagnostics?: (event: ObserveDiagnosticEvent | ReplayDiagnosticEvent) => void;
+    /**
+     * Explicit environment for zero-config governance mode selection.
+     * - "development" → monitor mode (log, don't block)
+     * - "staging" → protect mode (warn, don't block)
+     * - "production" → govern mode (block violations)
+     * Falls back to NODE_ENV if not set.
+     * @see zero-config-governance.md § Environment promotion
+     */
+    environment?: "development" | "staging" | "production";
 };
 /**
  * Raw tool executor provided by the user in `replay()` options.
@@ -1305,6 +1314,14 @@ type HandoffOfferResult = {
     eventSeq: number;
     stateVersion: number;
 };
+type GovernancePlanResult = {
+    status: string;
+    compiledSession?: unknown;
+    compiledHash?: string;
+    observations?: number;
+    confidence?: string;
+    version?: number;
+};
 type RuntimeClientHealth = {
     circuitOpen: boolean;
     failureCount: number;
@@ -1336,6 +1353,12 @@ declare class RuntimeClient {
     getWorkflowState(workflowId: string): Promise<WorkflowStateResult>;
     /** v4: Offer a handoff from a session. */
     offerHandoff(input: HandoffOfferInput): Promise<HandoffOfferResult>;
+    /**
+     * Fetch governance plan for an agent.
+     * Returns null on 404 (no plan exists).
+     * @see zero-config-governance.md § GET /api/v1/governance/plan
+     */
+    fetchGovernancePlan(agent: string, environment?: string): Promise<GovernancePlanResult | null>;
     getHealth(): RuntimeClientHealth;
     isCircuitOpen(): boolean;
     private get;

package/dist/index.d.ts

@@ -587,6 +587,15 @@ type ReplayOptions = {
     runtimeUrl?: string;
     captureLevel?: CapturePrivacyTier;
     diagnostics?: (event: ObserveDiagnosticEvent | ReplayDiagnosticEvent) => void;
+    /**
+     * Explicit environment for zero-config governance mode selection.
+     * - "development" → monitor mode (log, don't block)
+     * - "staging" → protect mode (warn, don't block)
+     * - "production" → govern mode (block violations)
+     * Falls back to NODE_ENV if not set.
+     * @see zero-config-governance.md § Environment promotion
+     */
+    environment?: "development" | "staging" | "production";
 };
 /**
  * Raw tool executor provided by the user in `replay()` options.
@@ -1305,6 +1314,14 @@ type HandoffOfferResult = {
     eventSeq: number;
     stateVersion: number;
 };
+type GovernancePlanResult = {
+    status: string;
+    compiledSession?: unknown;
+    compiledHash?: string;
+    observations?: number;
+    confidence?: string;
+    version?: number;
+};
 type RuntimeClientHealth = {
     circuitOpen: boolean;
     failureCount: number;
@@ -1336,6 +1353,12 @@ declare class RuntimeClient {
     getWorkflowState(workflowId: string): Promise<WorkflowStateResult>;
     /** v4: Offer a handoff from a session. */
     offerHandoff(input: HandoffOfferInput): Promise<HandoffOfferResult>;
+    /**
+     * Fetch governance plan for an agent.
+     * Returns null on 404 (no plan exists).
+     * @see zero-config-governance.md § GET /api/v1/governance/plan
+     */
+    fetchGovernancePlan(agent: string, environment?: string): Promise<GovernancePlanResult | null>;
     getHealth(): RuntimeClientHealth;
     isCircuitOpen(): boolean;
     private get;

package/dist/index.js

@@ -2173,6 +2173,7 @@ import {
 
 // src/contracts.ts
 import {
+  fillContractDefaults,
   hashToolSchema,
   loadContractSync,
   normalizeToolArray as normalizeToolArray2
@@ -2300,7 +2301,6 @@ function normalizeInlineContract(input) {
   if (!tool) {
     throw new ReplayConfigurationError("Inline contract is missing required field: tool");
   }
-  const assertions = toRecord5(source.assertions);
   const expectTools = toStringArray(source.expect_tools);
   const expectedToolCalls = toExpectedToolCalls(source.expected_tool_calls);
   const contract = {
@@ -2308,28 +2308,38 @@ function normalizeInlineContract(input) {
     ...toString5(source.tool_schema_hash) ? { tool_schema_hash: toString5(source.tool_schema_hash) } : {},
     ...isSideEffect(source.side_effect) ? { side_effect: source.side_effect } : {},
     ...toString5(source.contract_file) ? { contract_file: toString5(source.contract_file) } : {},
-    timeouts: {
-      total_ms: toNonNegativeNumber(toRecord5(source.timeouts).total_ms, 0)
-    },
-    retries: {
-      max_attempts: Math.max(1, toNonNegativeNumber(toRecord5(source.retries).max_attempts, 1)),
-      retry_on: toStringArray(toRecord5(source.retries).retry_on)
-    },
-    rate_limits: {
-      on_429: {
-        respect_retry_after: toBoolean(toRecord5(toRecord5(source.rate_limits).on_429).respect_retry_after, false),
-        max_sleep_seconds: toNonNegativeNumber(
-          toRecord5(toRecord5(source.rate_limits).on_429).max_sleep_seconds,
-          0
-        )
+    ...source.timeouts != null ? {
+      timeouts: { total_ms: toNonNegativeNumber(toRecord5(source.timeouts).total_ms, 0) }
+    } : {},
+    ...source.retries != null ? {
+      retries: {
+        max_attempts: Math.max(1, toNonNegativeNumber(toRecord5(source.retries).max_attempts, 1)),
+        retry_on: toStringArray(toRecord5(source.retries).retry_on)
       }
-    },
-    assertions: {
-      input_invariants: toInvariantArray(assertions.input_invariants),
-      output_invariants: toInvariantArray(assertions.output_invariants)
-    },
-    golden_cases: Array.isArray(source.golden_cases) ? source.golden_cases : [],
-    allowed_errors: toStringArray(source.allowed_errors),
+    } : {},
+    ...source.rate_limits != null ? {
+      rate_limits: {
+        on_429: {
+          respect_retry_after: toBoolean(toRecord5(toRecord5(source.rate_limits).on_429).respect_retry_after, false),
+          max_sleep_seconds: toNonNegativeNumber(
+            toRecord5(toRecord5(source.rate_limits).on_429).max_sleep_seconds,
+            0
+          )
+        }
+      }
+    } : {},
+    ...source.assertions != null ? {
+      assertions: {
+        input_invariants: toInvariantArray(toRecord5(source.assertions).input_invariants),
+        output_invariants: toInvariantArray(toRecord5(source.assertions).output_invariants)
+      }
+    } : {},
+    ...source.golden_cases != null ? {
+      golden_cases: Array.isArray(source.golden_cases) ? source.golden_cases : []
+    } : {},
+    ...source.allowed_errors != null ? {
+      allowed_errors: toStringArray(source.allowed_errors)
+    } : {},
     ...expectTools.length > 0 ? { expect_tools: expectTools } : {},
     ...toToolOrder(source.tool_order, expectTools.length > 0) ? {
       tool_order: toToolOrder(source.tool_order, expectTools.length > 0)
@@ -2355,8 +2365,9 @@ function normalizeInlineContract(input) {
     ...Array.isArray(source.schema_derived_exclude) ? { schema_derived_exclude: source.schema_derived_exclude } : {},
     ...Array.isArray(source.binds) ? { binds: source.binds } : {}
   };
-  validateSafeRegexes(contract);
-  return contract;
+  const filled = { ...fillContractDefaults(contract), ...contract.contract_file ? { contract_file: contract.contract_file } : {} };
+  validateSafeRegexes(filled);
+  return filled;
 }
 function validateContractSet(contracts) {
   const seenKeys = /* @__PURE__ */ new Set();
@@ -2375,11 +2386,11 @@ function validateSafeRegexes(contract) {
   const invariantGroups = [
     {
       label: "assertions.input_invariants",
-      invariants: contract.assertions.input_invariants
+      invariants: contract.assertions?.input_invariants ?? []
     },
     {
       label: "assertions.output_invariants",
-      invariants: contract.assertions.output_invariants
+      invariants: contract.assertions?.output_invariants ?? []
     }
   ];
   for (const [index, expectedToolCall] of (contract.expected_tool_calls ?? []).entries()) {
@@ -2982,7 +2993,7 @@ function evaluateExpectTools(contract, toolCalls) {
 function evaluateOutputInvariants(contract, normalizedResponse) {
   const invariantFailures = evaluateInvariants(
     normalizedResponse,
-    contract.assertions.output_invariants,
+    contract.assertions?.output_invariants ?? [],
     process.env
   );
   return invariantFailures.map(
@@ -3032,7 +3043,7 @@ function evaluateArgumentInvariants(contract, toolCalls) {
   return failures;
 }
 function mapInvariantFailure(contract, failure, normalizedResponse) {
-  const invariant = findMatchingInvariant(contract.assertions.output_invariants, failure);
+  const invariant = findMatchingInvariant(contract.assertions?.output_invariants ?? [], failure);
   const lookup = getPathValue(normalizedResponse, failure.path);
   return {
     path: failure.path,
@@ -3767,7 +3778,7 @@ function createInitialState(sessionId, options) {
     checkpointCount: 0
   };
 }
-function finalizeExecutedStep(state, step, contracts, compiledSession) {
+function finalizeExecutedStep(state, step, contracts, compiledSession, options) {
   const newSteps = [...state.steps, step];
   const newToolCallCounts = updateToolCallCounts(state.toolCallCounts, step);
   const resolvedContracts = compiledSession ? Array.from(compiledSession.perToolContracts.values()) : contracts;
@@ -3777,7 +3788,7 @@ function finalizeExecutedStep(state, step, contracts, compiledSession) {
     step
   );
   const costDelta = computeStepCost(step);
-  const newPhase = compiledSession ? recomputePhaseFromCommitted(step.toolCalls, state, compiledSession) : state.currentPhase;
+  const newPhase = options?.deferPhase ? state.currentPhase : compiledSession ? recomputePhaseFromCommitted(step.toolCalls, state, compiledSession) : state.currentPhase;
   return {
     ...state,
     steps: newSteps,
@@ -4625,7 +4636,7 @@ function validateToolResultMessages(messages, contracts, provider) {
   for (const result of toolResults) {
     const contract = contractByTool.get(result.toolName);
     if (!contract) continue;
-    const outputInvariants = contract.assertions.output_invariants;
+    const outputInvariants = contract.assertions?.output_invariants ?? [];
     if (outputInvariants.length === 0) continue;
     let parsed;
     try {
@@ -5275,6 +5286,32 @@ var RuntimeClient = class {
       stateVersion: h.state_version
     };
   }
+  /**
+   * Fetch governance plan for an agent.
+   * Returns null on 404 (no plan exists).
+   * @see zero-config-governance.md § GET /api/v1/governance/plan
+   */
+  async fetchGovernancePlan(agent, environment) {
+    const env = environment ?? "development";
+    try {
+      const data = await this.get(
+        `/api/v1/governance/plan?agent=${encodeURIComponent(agent)}&environment=${encodeURIComponent(env)}`
+      );
+      return {
+        status: data.status,
+        compiledSession: data.compiled_session,
+        compiledHash: data.compiled_hash,
+        observations: data.observations,
+        confidence: data.confidence,
+        version: data.version
+      };
+    } catch (err) {
+      if (err instanceof RuntimeClientError && err.httpStatus === 404) {
+        return null;
+      }
+      throw err;
+    }
+  }
   getHealth() {
     return {
       circuitOpen: this.now() < this.circuitOpenUntil,
@@ -5441,9 +5478,14 @@ function replay(client, opts = {}) {
     return createInactiveSession(client, sessionId, "Client already has an active observe() or replay() attachment");
   }
   let contracts;
+  let zeroConfigMode = false;
   try {
     contracts = resolveContracts(opts);
   } catch (err) {
+    const apiKeyForGov = resolveApiKey2(opts);
+    if (apiKeyForGov && !opts.contracts && !opts.contractsDir) {
+      return createGovernanceSession(client, sessionId, agent, provider, apiKeyForGov, opts, diagnostics);
+    }
     const detail = err instanceof Error ? err.message : "Failed to load contracts";
     emitDiagnostic2(diagnostics, { type: "replay_compile_error", details: detail });
     return createBlockingInactiveSession(client, sessionId, detail);
@@ -5650,6 +5692,8 @@ function replay(client, opts = {}) {
   let shadowEvaluationCount = 0;
   let manualFilter = null;
   const deferredReceipts = /* @__PURE__ */ new Map();
+  let deferredPhase = null;
+  const hasWrappedTools = opts.tools != null && Object.keys(opts.tools).length > 0;
   const contractLimits = resolveSessionLimits(contracts);
   const compiledLimits = compiledSession?.sessionLimits;
   const mergedLimits = { ...contractLimits ?? {}, ...compiledLimits ?? {} };
@@ -5786,6 +5830,7 @@ function replay(client, opts = {}) {
       total_ms: 0,
       enforcement_ms: 0
     };
+    deferredPhase = null;
     const trace = createTrace(sessionState.totalStepCount);
     const traceCtx = { trace };
     let currentTraceStage = "narrow";
@@ -6608,9 +6653,29 @@ function replay(client, opts = {}) {
                 }
               }
             }
+            const compatHasPhaseTransition = !!(phaseResult?.legal && phaseResult.newPhase !== sessionState.currentPhase);
+            const compatShouldDefer = hasWrappedTools && compatHasPhaseTransition;
             const prevVersion = sessionState.stateVersion;
-            sessionState = finalizeExecutedStep(sessionState, completedStep, contracts, compiledSession);
+            sessionState = finalizeExecutedStep(
+              sessionState,
+              completedStep,
+              contracts,
+              compiledSession,
+              compatShouldDefer ? { deferPhase: true } : void 0
+            );
             syncStateToStore(prevVersion, sessionState);
+            if (compatShouldDefer && compiledSession && phaseResult) {
+              const advancingTools = /* @__PURE__ */ new Set();
+              for (const tc of toolCalls) {
+                const contract = compiledSession.perToolContracts.get(tc.name);
+                if (contract?.transitions?.advances_to === phaseResult.newPhase) {
+                  advancingTools.add(tc.name);
+                }
+              }
+              if (advancingTools.size > 0 && phaseResult.newPhase != null) {
+                deferredPhase = { newPhase: phaseResult.newPhase, toolNames: advancingTools };
+              }
+            }
           }
           if (advisoryDecision.action === "block") {
             sessionState = recordDecisionOutcome(sessionState, "blocked");
@@ -6700,11 +6765,31 @@ function replay(client, opts = {}) {
               }
             }
           }
+          const hasPhaseTransition = phaseResult?.legal && phaseResult.newPhase !== sessionState.currentPhase;
+          const shouldDeferPhase = hasWrappedTools && !!hasPhaseTransition;
           const prevVersionAllow = sessionState.stateVersion;
-          sessionState = finalizeExecutedStep(sessionState, completedStep, contracts, compiledSession);
+          sessionState = finalizeExecutedStep(
+            sessionState,
+            completedStep,
+            contracts,
+            compiledSession,
+            shouldDeferPhase ? { deferPhase: true } : void 0
+          );
           sessionState = recordDecisionOutcome(sessionState, "allowed");
           syncStateToStore(prevVersionAllow, sessionState);
           timing.finalize_ms += Date.now() - enforceFinalizeStart;
+          if (shouldDeferPhase && compiledSession) {
+            const advancingTools = /* @__PURE__ */ new Set();
+            for (const tc of toolCalls) {
+              const contract = compiledSession.perToolContracts.get(tc.name);
+              if (contract?.transitions?.advances_to === phaseResult.newPhase) {
+                advancingTools.add(tc.name);
+              }
+            }
+            if (advancingTools.size > 0 && phaseResult.newPhase != null) {
+              deferredPhase = { newPhase: phaseResult.newPhase, toolNames: advancingTools };
+            }
+          }
           if (isActiveGovern && !attemptDegraded && attemptPendingCalls && attemptPendingCalls.size > 0) {
             for (const [toolCallId, pending] of attemptPendingCalls) {
               deferredReceipts.set(toolCallId, {
@@ -6722,8 +6807,8 @@ function replay(client, opts = {}) {
             checked: { gate_mode: gateMode },
             found: { blocked_count: 0, action: "allow" }
           });
-          const allowNewPhase = phaseResult && phaseResult.legal && phaseResult.newPhase !== sessionState.currentPhase ? phaseResult.newPhase : sessionState.currentPhase;
-          trace.push({ stage: "finalize", tool: null, verdict: "info", reason: "cycle_complete", checked: {}, found: { state_version: sessionState.stateVersion, phase_before: completedStep.phase, phase_after: allowNewPhase, tools_committed: toolCalls.map((tc) => tc.name), tools_blocked: [], killed: false, step_index: sessionState.totalStepCount } });
+          const allowNewPhase = phaseResult && phaseResult.legal && phaseResult.newPhase !== (completedStep.phase ?? sessionState.currentPhase) ? phaseResult.newPhase : sessionState.currentPhase;
+          trace.push({ stage: "finalize", tool: null, verdict: "info", reason: "cycle_complete", checked: {}, found: { state_version: sessionState.stateVersion, phase_before: completedStep.phase, phase_after: allowNewPhase, ...shouldDeferPhase ? { phase_deferred: true } : {}, tools_committed: toolCalls.map((tc) => tc.name), tools_blocked: [], killed: false, step_index: sessionState.totalStepCount } });
           trace.complete = true;
           lastTrace = trace;
           emitDiagnostic2(diagnostics, { type: "replay_trace", session_id: sessionId, trace });
@@ -7070,6 +7155,10 @@ function replay(client, opts = {}) {
           throw new ReplayKillError(sessionId, killedAt);
         }
         const result = await executor(args);
+        if (deferredPhase && deferredPhase.toolNames.has(toolName)) {
+          sessionState = { ...sessionState, currentPhase: deferredPhase.newPhase };
+          deferredPhase = null;
+        }
         if (runtimeClient && leaseFence && !runtimeDegraded) {
           for (const [callId, deferred] of deferredReceipts) {
             if (deferred.toolName === toolName) {
@@ -7320,7 +7409,7 @@ function validateResponse2(response, toolCalls, contracts, requestToolNames, unm
     }
   }
   for (const contract of matched) {
-    const outputInvariants = contract.assertions.output_invariants;
+    const outputInvariants = contract.assertions?.output_invariants ?? [];
     if (outputInvariants.length > 0) {
       const normalizedResponse = buildNormalizedResponse(response, toolCalls);
       const result = evaluateInvariants4(normalizedResponse, outputInvariants, process.env);
@@ -7488,8 +7577,9 @@ function evaluateInputInvariants(request, contracts) {
   const requestToolSet = new Set(requestToolNames);
   for (const contract of contracts) {
     if (!requestToolSet.has(contract.tool)) continue;
-    if (contract.assertions.input_invariants.length === 0) continue;
-    const result = evaluateInvariants4(request, contract.assertions.input_invariants, process.env);
+    const inputInvariants = contract.assertions?.input_invariants ?? [];
+    if (inputInvariants.length === 0) continue;
+    const result = evaluateInvariants4(request, inputInvariants, process.env);
     for (const failure of result) {
       failures.push({
         path: failure.path,
@@ -7864,6 +7954,126 @@ function createBlockingInactiveSession(client, sessionId, detail, configError) {
     handoff: () => Promise.resolve(null)
   };
 }
+function resolveGovernanceEnvironment(opts) {
+  if (opts.environment) return opts.environment;
+  const envVar = typeof process !== "undefined" ? process.env.REPLAYCI_ENVIRONMENT : void 0;
+  if (envVar === "staging") return "staging";
+  if (envVar === "production") return "production";
+  if (envVar === "development") return "development";
+  const nodeEnv = typeof process !== "undefined" ? process.env.NODE_ENV : void 0;
+  if (nodeEnv === "production") return "production";
+  return "development";
+}
+function governanceProtectionLevel(env) {
+  switch (env) {
+    case "production":
+      return "govern";
+    case "staging":
+      return "protect";
+    default:
+      return "monitor";
+  }
+}
+function createGovernanceSession(client, sessionId, agent, provider, apiKey, opts, diagnostics) {
+  const environment = resolveGovernanceEnvironment(opts);
+  const protLevel = governanceProtectionLevel(environment);
+  const runtimeClient = new RuntimeClient({
+    apiKey,
+    apiUrl: opts.runtimeUrl
+  });
+  let governancePlan;
+  let planFetchPromise = null;
+  let planFetchDone = false;
+  let planFetchError = null;
+  planFetchPromise = runtimeClient.fetchGovernancePlan(agent, environment).then((result) => {
+    governancePlan = result;
+    planFetchDone = true;
+  }).catch((err) => {
+    planFetchDone = true;
+    planFetchError = err instanceof Error ? err.message : String(err);
+    governancePlan = null;
+  });
+  const captureBuffer = new CaptureBuffer({
+    apiKey,
+    endpoint: opts.runtimeUrl
+  });
+  registerBeforeExit(captureBuffer);
+  const terminalInfo = resolveTerminal(client, provider);
+  if (!terminalInfo) {
+    emitDiagnostic2(diagnostics, { type: "replay_inactive", reason: "unsupported_client" });
+    return createInactiveSession(client, sessionId, "Could not resolve terminal resource");
+  }
+  const { terminal, originalCreate } = terminalInfo;
+  const patchedCreate = async function(...args) {
+    if (!planFetchDone && planFetchPromise) {
+      await planFetchPromise;
+    }
+    const hasApprovedPlan = governancePlan && (governancePlan.status === "approved" || governancePlan.status === "enforcing") && governancePlan.compiledSession;
+    if (hasApprovedPlan) {
+    }
+    const result = await originalCreate.apply(this, args);
+    try {
+      const toolCalls = extractToolCalls(result, provider);
+      const usage = extractUsage(result, provider);
+      const requestArg = args[0] && typeof args[0] === "object" ? args[0] : {};
+      captureBuffer.push({
+        schema_version: CAPTURE_SCHEMA_VERSION_CURRENT,
+        agent,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        provider,
+        model_id: requestArg.model ?? "unknown",
+        primary_tool_name: toolCalls[0]?.name ?? null,
+        tool_names: toolCalls.map((tc) => tc.name),
+        request: requestArg,
+        response: result,
+        usage,
+        latency_ms: 0,
+        sdk_session_id: sessionId
+      });
+    } catch {
+    }
+    return result;
+  };
+  terminal[terminalInfo.methodName] = patchedCreate;
+  setReplayAttached(client);
+  return {
+    client,
+    flush: () => captureBuffer.flush(),
+    restore() {
+      terminal[terminalInfo.methodName] = originalCreate;
+    },
+    kill() {
+    },
+    getHealth: () => ({
+      status: "healthy",
+      authorityState: "active",
+      protectionLevel: protLevel,
+      durability: "inactive",
+      tier: "compat",
+      compatEnforcement: "protective",
+      cluster_detected: false,
+      bypass_detected: false,
+      totalSteps: 0,
+      totalBlocks: 0,
+      totalErrors: 0,
+      killed: false,
+      shadowEvaluations: 0
+    }),
+    getState: () => EMPTY_STATE_SNAPSHOT,
+    getLastNarrowing: () => null,
+    getLastShadowDelta: () => null,
+    getLastTrace: () => null,
+    narrow() {
+    },
+    widen() {
+    },
+    addLabel() {
+    },
+    tools: {},
+    getWorkflowState: () => Promise.resolve(null),
+    handoff: () => Promise.resolve(null)
+  };
+}
 function toNarrowingSnapshot(result) {
   if (!result || result.removed.length === 0) return null;
   return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@replayci/replay",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "description": "ReplayCI SDK for deterministic tool-call validation and observation.",
   "license": "ISC",
   "author": "ReplayCI",