Skip to main content

Govern Mode

Govern mode connects replay() to the Vesanor server for durable session state, server-backed coordination, and stronger evidence. It is the strongest Replay mode today.

When you need Govern​

Protect mode (local enforcement) is sufficient for most use cases. Use Govern mode when:

  • You need session state to survive process crashes
  • You need Replay to durably record governed calls with specific arguments
  • Multiple workers share the same agent session
  • You want approvals, kills, and labels reflected in server-backed session state
  • You need server-side kill propagation

Setting up Govern mode​

Two things separate Govern from Protect:

  1. API key — connects to the Vesanor server
  2. Tool wrappers — wraps your tool executors for governed execution
import OpenAI from "openai";
import { replay } from "@vesanor/replay";

const client = new OpenAI();

const session = replay(client, {
  contractsDir: "./contracts",
  agent: "refund-support-bot",
  mode: "enforce",
  apiKey: process.env.VESANOR_API_KEY,      // Connects to server
  tools: {                                     // Governed execution
    issue_refund: async (args) => {
      const result = await myRefundService.process(args);
      return result;
    },
    delete_record: async (args) => {
      await myDatabase.delete(args.record_id);
      return { deleted: true };
    },
  },
});

The govern pipeline​

Every LLM call goes through this server-backed pipeline:

1. PREFLIGHT    → SDK sends request envelope to server
                  Server binds it to current session state version
                  Returns a prepared_request_id (single-use)

2. LLM CALL     → Normal provider API call

3. PROPOSAL     → SDK sends the LLM's response to server
                  Server evaluates against session state + contracts
                  Registers pending calls atomically
                  Returns allow/block decision

4. EXECUTION    → SDK runs your tool wrapper (if provided)
                  Records execution evidence

5. RECEIPT      → SDK sends execution evidence to server
                  Server records governed execution receipt
                  Makes commit decision based on evidence level

6. COMMIT       → Server advances authoritative session state
                  Only when commit_requirement is satisfied

Key properties:

  • Each prepared request is single-use — can't be replayed
  • Prepared requests are bound to session state — if state changes between preflight and proposal, the proposal is rejected
  • Receipts are governed execution evidence — Replay's durable record that a wrapped tool path ran with specific arguments
  • State advances only on explicit commit — not on proposal alone

What tool wrappers give you​

Without tool wrappers, replay() enforces contracts but can't attach governed execution evidence to a specific tool path:

// Protect mode — no wrappers
const session = replay(client, {
  mode: "enforce",
  // No apiKey, no tools
});
// Protection level: Protect (blocking, local-only)

With tool wrappers, replay() can record governed execution on the wrapped path:

// Govern mode — full wrappers
const session = replay(client, {
  mode: "enforce",
  apiKey: process.env.VESANOR_API_KEY,
  tools: {
    issue_refund: myRefundFunction,
  },
});
// Protection level: Govern (blocking + durable governed record)

What wrappers enable:

  • Execution constraints enforced before your function runs
  • Governed execution receipts with argument hashes
  • Authoritative commit decisions
  • Full audit trail

Health and durability​

Check the session's connection to the server:

const health = session.getHealth();
console.log(health.protectionLevel);  // "govern"
console.log(health.durability);       // "server" | "degraded-local" | "inactive"
console.log(health.authorityState);   // "active" | "advisory" | "compromised" | "recovering" | "killed" | "inactive"
console.log(health.tier);             // "strong" | "compat"
DurabilityMeaning
serverConnected, state is durable
degraded-localServer unreachable, falling back to local enforcement
inactiveNo server connection configured

Graceful degradation​

If the server becomes unreachable, Govern mode degrades gracefully:

const session = replay(client, {
  mode: "enforce",
  apiKey: process.env.VESANOR_API_KEY,
  tools: { issue_refund: myRefundFunction },
  onError: "block",           // Default: block on server failure
  // onError: "allow",        // Alternative: continue with local enforcement
});

With onError: "block" (default), server failures block the call — fail closed.

With onError: "allow", the SDK falls back to local enforcement. Calls proceed but are not durably recorded. The totalUnguardedCalls counter tracks how many calls ran without server backing.

Bypass detection​

In Govern mode, the SDK detects if you call the original client directly (bypassing the wrapper):

const session = replay(client, {
  mode: "enforce",
  apiKey: process.env.VESANOR_API_KEY,
  tools: { issue_refund: myRefundFunction },
});

// DON'T DO THIS — use session.client instead
const response = await client.chat.completions.create({
  model: "gpt-4o-mini",
  messages,
  tools,
});
// ^ This triggers bypass detection!

When bypass is detected:

  1. A replay_bypass_detected diagnostic event is emitted
  2. The session is marked compromised on the server
  3. Future authoritative writes are rejected for this session
  4. The call still goes through (can't be blocked in TypeScript)

Why this matters: The wrapper is how replay() maintains session state. Calls that bypass it create invisible state that the governance system doesn't know about. A compromised session can't make authoritative claims.

Server-side session state​

In Govern mode, you can verify server state through the database or API:

// After 4 tool calls...
const health = session.getHealth();
console.log(health.totalSteps);    // 4
console.log(health.totalBlocks);   // 0

// Server has:
// - ReplaySession row (mode: AUTHORITATIVE, status: ACTIVE)
// - 4 ReplayPreparedRequest rows (each consumed_at set)
// - 4 ReplayPendingCall rows (each resolved)
// - 4 ReplayExecutionReceipt rows (governed evidence)
// - state_version: 4

Server-backed session state​

In Govern mode, the server maintains the durable session record for prepared requests, pending calls, execution receipts, commit status, kill state, and session compromise state. Replay also supports server-backed labels and workflow coordination when those features are configured.

Session labels​

Labels are persisted in the ReplaySession model and can be applied during server-side preflight. The server:

  1. Accepts labels at session creation and via POST /sessions/:id/labels
  2. Enforces append-only semantics (no removal endpoint)
  3. Evaluates label_gates during narrowing — tools denied by active labels are removed from the preflight response

A compromised client cannot clear labels from the server-side session record locally.

Governed receipts and commits​

The server maintains the durable sequence of prepared requests, pending calls, and execution receipts:

  • Prepared requests are bound to a session state version
  • Pending calls are resolved durably on the server
  • Commit decisions advance the server-backed session record only when the required evidence is present

This gives Govern stronger durability and recovery properties than local-only Protect mode.

Checkpoint approvals​

Checkpoints are where Govern most clearly adds server-backed coordination:

  1. The SDK submits a proposal containing a tool call that triggers a checkpoint
  2. The server evaluates checkpoint conditions and sets the proposal to pending_approval
  3. An external system (Slack bot, dashboard, webhook) calls POST /sessions/:id/proposals/:id/approve
  4. The server resolves the proposal and the SDK receives the decision

In Govern mode, the server controls the approval state for that session.

Key properties:

  • Minimum timeout of 30 seconds (clamped server-side)
  • Maximum 10 checkpoint triggers per session (checkpoint_budget_exceeded after that)
  • on_timeout: deny is the default and recommended setting
  • Checkpoints do NOT trigger in shadow mode

Workflow coordination​

When you use Workflow Governance, the server can also coordinate shared workflow state across multiple sessions, including durable workflow status and resource-level conflict checks.

Trust model​

Govern gives Replay durable session state and stronger receipts on the wrapped path. For details on evidence, bypasses, and how Replay fits with other controls, see Security & Evidence.

When to use Protect vs Govern​

ScenarioRecommendation
Single-process agent, no durable server trail neededProtect
Need to block bad calls, no audit trail neededProtect
Multiple workers sharing a sessionGovern
Need durable governed records for wrapped pathsGovern
High-risk workflows with approvals or shared stateGovern
Development and testingProtect (faster, no server needed)
Latency-sensitive local workflowsProtect

Next steps​