API Reference

Gate.run(spec)

Run a gate. Returns a result with status, logs, and evidence.

• spec.name is optional metadata
• spec.observe defines how logs are collected
• spec.act triggers behavior
• spec.assert verifies evidence
• spec.stop defines idleMs and maxMs

Actions

Act.exec("command")              // Run shell command
Act.browser({ url, headless? })  // Browser automation (playwright)
Act.wait(ms)                     // Sleep
Act.deploy({ worker })           // Deploy marker

Agent Actions

Act.agent({
  name: "fix-auth",               // Display name
  agent: "claude-code",           // Agent type: "claude-code" | "codex" | "cursor" | image
  model: "claude-sonnet-4-20250514",
  task: "Fix the null pointer",   // Natural language task (→ FILEPATH_TASK env var)
  repo?: "https://github.com/...",  // Git repo to clone into /workspace
  env?: { KEY: "value" },         // Extra environment variables
  timeoutMs?: 300_000,            // Default: 5 minutes
})

Container Runtime

import { setFilepathRuntime, CloudflareSandboxRuntime } from "gateproof";
import { getSandbox } from "@cloudflare/sandbox";

// Register once at startup
setFilepathRuntime(new CloudflareSandboxRuntime({
  getSandbox: (config) => getSandbox(env.Sandbox, `agent-${config.name}`),
  command?: (config) => ["my-agent", "--model", config.model],  // Override entrypoint
}));

Or spawn containers manually and observe them directly:

import { createFilepathObserveResource } from "gateproof";

const container = await runtime.spawn(config);
const observe = createFilepathObserveResource(container, "my-agent");

The container's stdout must emit NDJSON (one JSON object per line). Supported event types: text, tool, command, commit, spawn, workers, status, handoff, done.

Assertions

Assert.noErrors()
Assert.hasAction("name")
Assert.hasStage("stage")
Assert.custom("name", (logs) => boolean)
Assert.authority({
  canCommit: true,          // Agent is allowed to commit
  canSpawn: false,          // Agent must NOT spawn child agents
  forbiddenTools: ["delete_file"],  // Tools the agent must not use
})

Assert.authority() checks the agent's actual behavior (commits, spawns, tool calls observed in logs) against the policy you define. Fails if the agent exceeded its authority.

Result

{
  status: "success" | "failed" | "timeout",
  durationMs: number,
  logs: Log[],
  evidence: {
    requestIds: string[],
    stagesSeen: string[],
    actionsSeen: string[],
    errorTags: string[]
  },
  error?: Error
}

JSON Schemas for AI Agents

Contributed by @grok

Gate results and PRD reports are fully JSON-serializable for machine consumption. Use these schemas to parse gate outputs in agent pipelines.

GateResultV1

{
  "version": "1",
  "status": "success | failed | timeout",
  "durationMs": 1234,
  "logs": [],
  "evidence": {
    "requestIds": ["req-abc"],
    "stagesSeen": ["worker", "db"],
    "actionsSeen": ["user_created"],
    "errorTags": []
  },
  "error": {
    "tag": "AssertionFailed",
    "name": "AssertionFailed",
    "message": "HasAction: missing 'user_created'",
    "stack": "..."
  }
}

PrdReportV1

{
  "version": "1",
  "success": false,
  "stories": [
    {
      "id": "user-signup",
      "title": "User can sign up",
      "gateFile": "./gates/signup.gate.ts",
      "status": "failed",
      "durationMs": 5432,
      "error": { "tag": "AssertionFailed", "name": "AssertionFailed", "message": "..." }
    }
  ],
  "failedStory": {
    "id": "user-signup",
    "title": "User can sign up",
    "gateFile": "./gates/signup.gate.ts"
  },
  "totalDurationMs": 5432
}

LLMFailureSummary

Structured failure context optimized for AI agents. Generated by createLLMFailureSummary() from gateproof/report:

{
  "summary": "Gate \"user-signup\" failed: HasAction: missing 'user_created'",
  "failedAssertions": [
    {
      "name": "HasAction",
      "message": "missing 'user_created'",
      "expected": "user_created in logs",
      "actual": "not found"
    }
  ],
  "prdRelevantSlice": {
    "storyId": "user-signup",
    "storyTitle": "User can sign up",
    "gateFile": "./gates/signup.gate.ts",
    "scope": { "allowedPaths": ["src/routes/**"] }
  },
  "evidence": {
    "actionsSeen": ["page_load"],
    "stagesSeen": ["worker"],
    "errorTags": [],
    "logCount": 12
  },
  "diffSnippet": "diff --git a/src/routes/signup.ts ...",
  "suggestions": [
    "Ensure the code logs an action named 'user_created'",
    "Check if the relevant code path is being executed"
  ]
}

Usage in agent code:

import { createLLMFailureSummary } from "gateproof/report";

const summary = createLLMFailureSummary(prdReport, {
  prdSlice: { storyId: "user-signup", storyTitle: "...", gateFile: "..." },
  diffSnippet: recentGitDiff,
  logs: gateResult.logs,
});

// Feed to your agent as structured JSON
const agentPrompt = JSON.stringify(summary, null, 2);