@replayci/replay 0.1.14 → 0.1.16

package/dist/index.cjs

@@ -1188,6 +1188,14 @@ function optionalString(value, path) {
   }
   return value;
 }
+function extractReplayTrace(capture) {
+  const replay2 = capture.replay;
+  if (!isRecord(replay2)) return void 0;
+  const trace = replay2.trace;
+  if (!isRecord(trace)) return void 0;
+  if (!Array.isArray(trace.entries)) return void 0;
+  return trace;
+}
 function parseCommonCapture(capture, index, modelId, schemaVersion) {
   const toolNames = requireStringArray(capture.tool_names, `captures[${index}].tool_names`);
   const primaryToolName = capture.primary_tool_name === void 0 ? toolNames[0] ?? null : nullableString(capture.primary_tool_name, `captures[${index}].primary_tool_name`);
@@ -1205,7 +1213,8 @@ function parseCommonCapture(capture, index, modelId, schemaVersion) {
     ...capture.validation !== void 0 ? { validation: validateValidation(capture.validation, `captures[${index}].validation`) } : {},
     ...capture.usage !== void 0 ? { usage: validateUsage(capture.usage, `captures[${index}].usage`) } : {},
     latency_ms: requireNonNegativeInt(capture.latency_ms, `captures[${index}].latency_ms`),
-    ...sdkSessionId !== void 0 ? { sdk_session_id: sdkSessionId } : {}
+    ...sdkSessionId !== void 0 ? { sdk_session_id: sdkSessionId } : {},
+    ...extractReplayTrace(capture) !== void 0 ? { replay_trace: extractReplayTrace(capture) } : {}
   };
 }
 function parseLegacyCapturedCall(capture, index) {
@@ -2320,7 +2329,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 +2336,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 +2393,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 +2414,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 +3021,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 +3071,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,
@@ -4634,7 +4653,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 +5303,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 +5495,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);
@@ -5660,6 +5710,7 @@ function replay(client, opts = {}) {
   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 ?? {} };
@@ -6619,9 +6670,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");
@@ -6712,7 +6783,7 @@ function replay(client, opts = {}) {
             }
           }
           const hasPhaseTransition = phaseResult?.legal && phaseResult.newPhase !== sessionState.currentPhase;
-          const shouldDeferPhase = isActiveGovern && !attemptDegraded && hasPhaseTransition;
+          const shouldDeferPhase = hasWrappedTools && !!hasPhaseTransition;
           const prevVersionAllow = sessionState.stateVersion;
           sessionState = finalizeExecutedStep(
             sessionState,
@@ -7355,7 +7426,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);
@@ -7523,8 +7594,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,
@@ -7899,6 +7971,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

@@ -1142,6 +1142,14 @@ function optionalString(value, path) {
   }
   return value;
 }
+function extractReplayTrace(capture) {
+  const replay2 = capture.replay;
+  if (!isRecord(replay2)) return void 0;
+  const trace = replay2.trace;
+  if (!isRecord(trace)) return void 0;
+  if (!Array.isArray(trace.entries)) return void 0;
+  return trace;
+}
 function parseCommonCapture(capture, index, modelId, schemaVersion) {
   const toolNames = requireStringArray(capture.tool_names, `captures[${index}].tool_names`);
   const primaryToolName = capture.primary_tool_name === void 0 ? toolNames[0] ?? null : nullableString(capture.primary_tool_name, `captures[${index}].primary_tool_name`);
@@ -1159,7 +1167,8 @@ function parseCommonCapture(capture, index, modelId, schemaVersion) {
     ...capture.validation !== void 0 ? { validation: validateValidation(capture.validation, `captures[${index}].validation`) } : {},
     ...capture.usage !== void 0 ? { usage: validateUsage(capture.usage, `captures[${index}].usage`) } : {},
     latency_ms: requireNonNegativeInt(capture.latency_ms, `captures[${index}].latency_ms`),
-    ...sdkSessionId !== void 0 ? { sdk_session_id: sdkSessionId } : {}
+    ...sdkSessionId !== void 0 ? { sdk_session_id: sdkSessionId } : {},
+    ...extractReplayTrace(capture) !== void 0 ? { replay_trace: extractReplayTrace(capture) } : {}
   };
 }
 function parseLegacyCapturedCall(capture, index) {
@@ -2173,6 +2182,7 @@ import {
 
 // src/contracts.ts
 import {
+  fillContractDefaults,
   hashToolSchema,
   loadContractSync,
   normalizeToolArray as normalizeToolArray2
@@ -2300,7 +2310,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 +2317,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 +2374,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 +2395,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 +3002,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 +3052,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,
@@ -4625,7 +4645,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 +5295,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 +5487,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);
@@ -5651,6 +5702,7 @@ function replay(client, opts = {}) {
   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 ?? {} };
@@ -6610,9 +6662,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");
@@ -6703,7 +6775,7 @@ function replay(client, opts = {}) {
             }
           }
           const hasPhaseTransition = phaseResult?.legal && phaseResult.newPhase !== sessionState.currentPhase;
-          const shouldDeferPhase = isActiveGovern && !attemptDegraded && hasPhaseTransition;
+          const shouldDeferPhase = hasWrappedTools && !!hasPhaseTransition;
           const prevVersionAllow = sessionState.stateVersion;
           sessionState = finalizeExecutedStep(
             sessionState,
@@ -7346,7 +7418,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);
@@ -7514,8 +7586,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,
@@ -7890,6 +7963,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.14",
+  "version": "0.1.16",
   "description": "ReplayCI SDK for deterministic tool-call validation and observation.",
   "license": "ISC",
   "author": "ReplayCI",