gateproof 0.2.2 → 0.2.4

package/README.md

@@ -1,279 +1,89 @@
 # gateproof
 
-Build software in reverse. PRD defines what should exist. Gates verify reality. Agent iterations refine until gates pass.
+Software is built in reverse. You know what you want before you know how to get there. TDD proved the idea: write the test first, then make it pass. Gateproof takes the next step.
 
-## What gateproof does
+Write stories. Attach gates. Let agents iterate until reality matches intent.
 
-gateproof enables **agent iterations** with minimal context overhead.
+A **gate** observes real evidence (logs, telemetry), acts (browser, shell, deploy), and asserts outcomes. A **story** is a gate with a name and a place in a plan. A **prd.ts** is a list of stories in dependency order. The agent's only job is to make the next failing gate pass.
 
-**The workflow:**
-1. PRD defines stories (what should exist)
-2. Gates verify reality (does it work?)
-3. Agent gets PRD + gate failure (minimal context)
-4. Agent fixes, gates re-run
-5. Iterate until all gates pass
+## The thesis
 
-**Why this works:**
-- PRD is single source of truth (clear intent, minimal context)
-- Gates provide concrete feedback (not vague requirements)
-- Agent gets context only when needed (efficient)
-- Iteration ensures correctness (converges to working code)
+Plans are solid. Implementation is liquid.
 
-gateproof **executes gates**. It does not define intent, plans, or workflows. A gate is a test specification: observe logs, run actions, assert results. gateproof runs it and returns evidence.
+Any codebase can be scoped down to stories and a `prd.ts`. Multiple agents can work the same plan, falling through the same checkpoints. Once a gate passes, previous work can't break -- the gate proves it. The skill shifts from writing code to defining the right guardrails.
 
-**Authority chain:**
-- **PRD (`prd.ts`)** — authority on intent, order, and dependencies (if you use the PRD runner)
-- **Gate implementations** — authority on how reality is observed
-- **gateproof runtime** — authority on enforcement only
+Gates are checkpoints that keep agents safe. They don't decide intent. They verify reality.
 
-gateproof never decides *what* to build. It returns results; your CI/CD decides whether you are allowed to proceed.
+## Why this works
 
-## Agent skill: prdts-maker
+Formal verification research established that the relationship between a specification and its implementation — called **refinement** — is itself a testable property. You don't need a theorem prover to get value from this idea. You can test refinement cheaply by running the system and checking that its behavior satisfies the spec.
 
-This repo is agent-first. Use the `prdts-maker` skill to turn a prompt into a working `prd.ts`.
+Gateproof distills this into three primitives:
 
-**How to use it:**
-- Provide a prompt (big blob of text is fine).
-- Ask the agent to run the `prdts-maker` skill and output a complete `prd.ts`.
-- Save and run: `bun run prd.ts`.
+1. **Observe** — collect real evidence (logs, telemetry) from a running system
+2. **Act** — trigger real behavior (browser navigation, shell commands, deploys)
+3. **Assert** — check that the evidence satisfies the specification
 
-**Example prompt:**
-```text
-@prdts-maker Create prd.ts for:
-- User can sign up
-- Email verification works (depends on signup)
-- User can log in (depends on verification)
-Include gate files under ./gates/.
-```
-
-## CLI: npx gateproof prdts
+Each gate is a refinement check: does the running system's behavior refine what the story claims? The PRD orders these checks by dependency, so failures localize to the first broken obligation.
 
-Generate a `prd.ts` from a prompt without opening the repo.
+This is a deliberate simplification. We trade random input generation and exhaustive coverage for something an engineer can write in minutes and an agent can iterate against in a loop. The gate is the contract. The loop is the proof search.
 
-```bash
-echo "Build a signup flow with email verification and login" | npx gateproof prdts --stdout
-npx gateproof prdts --in stories.txt --out prd.ts
-```
+> Lineage: the *observe → act → assert* pattern draws on property-based testing ideas from [Chen, Rizkallah et al. — "Property-Based Testing: Climbing the Stairway to Verification" (SLE 2022)](https://doi.org/10.1145/3567512.3567520), which demonstrated that refinement properties can serve as a practical, incremental path toward verified systems.
 
-This calls Opencode directly. Set `OPENCODE_ZEN_API_KEY` (or pass `--api-key`).
-
-Paste mode (interactive stdin):
+## Install
 
 ```bash
-npx gateproof prdts
-# paste a prompt, then Ctrl-D
+bun add gateproof
 ```
 
-To target a different Opencode base URL or model:
+## Minimal gate
 
-```bash
-npx gateproof prdts --endpoint https://opencode.ai/zen/v1 --model big-pickle --in stories.txt --out prd.ts
-```
+```ts
+import { Gate, Act, Assert, createHttpObserveResource } from "gateproof";
 
-## Agent Iterations: The Loop
-
-The core innovation: agents work from PRD only, gates verify, iterate until correct.
-
-**The iteration loop:**
-1. Run PRD → executes gates in dependency order
-2. Gate fails → agent gets: codebase context (e.g., `AGENTS.md`) + failure output
-3. Agent fixes → makes changes to codebase
-4. Loop repeats → re-run PRD, check if gates pass
-5. All gates pass → done
-
-**Why minimal context:**
-- Agent starts with PRD only (no full codebase upfront)
-- Agent gets context only when gates fail (just-in-time)
-- PRD stays as authority (what to build)
-- Gates provide concrete feedback (what's wrong)
+const result = await Gate.run({
+  name: "post-deploy",
+  observe: createHttpObserveResource({
+    url: "https://api.example.com/health",
+  }),
+  act: [Act.wait(500)],
+  assert: [Assert.noErrors()],
+  stop: { maxMs: 10_000 },
+});
 
-**Example loop script:**
-```bash
-# patterns/prd/agent-iteration-loop.sh
-while true; do
-  bun run prd.ts || {
-    # Gate failed - agent gets PRD + failure output
-    agent --context prd.ts --failure "$(cat gate-output.txt)"
-    # Agent fixes, loop continues
-  }
-  break  # All gates passed
-done
+if (result.status !== "success") process.exit(1);
 ```
 
-**The guardrails:**
-- Max failures (default: 5) → auto-pause if stuck
-- Git diff check → agent must make changes
-- Pause file → manual control
-
-This solves the context management problem: agents don't need full codebase context upfront. They get minimal context (PRD), concrete feedback (gate failures), and iterate until correct.
-
-## Anatomy of a prd.ts (1 list)
-
-1. **Instructions**: each story title encodes behavior + evidence + scope (the agent's marching orders).
-2. **Stories**: `stories[]` holds `{ id, title, gateFile, dependsOn?, progress? }` in execution order.
-3. **Gates**: `gateFile` points at a gate script that observes logs, acts, and asserts evidence.
-4. **Loop state**: `runPrd(...)` returns success or the `failedStory` plus gate evidence (actions/stages/errors).
-5. **Loop instructions**: on failure, feed the agent `prd.ts` + gate output, fix code, re-run PRD until pass.
-
-## Stories as gates
-
-A PRD (Product Requirements Document) defines stories. Stories are gates. Each story references a gate file. The gate file verifies the story against reality.
-
-Reality is the source of truth; gates make it enforceable in CI.
+## Stories + PRD
 
-### prd.ts example
-
-```typescript
-// prd.ts
-import { definePrd } from "gateproof/prd";
+```ts
+import { definePrd, runPrd } from "gateproof/prd";
 
-export const prd = definePrd({
+const prd = definePrd({
   stories: [
     {
       id: "user-signup",
-      title: "User can sign up",
-      gateFile: "./gates/user-signup.gate.ts",
-      progress: ["signup_page_live", "user_created"],
+      title: "User can sign up with email",
+      gateFile: "./gates/signup.gate.ts",
     },
     {
       id: "email-verification",
       title: "User receives verification email",
-      gateFile: "./gates/email-verification.gate.ts",
+      gateFile: "./gates/verify.gate.ts",
       dependsOn: ["user-signup"],
-      progress: ["email_sent", "verification_link_valid"],
     },
-  ] as const, // keep story IDs as literal types
+  ] as const,
 });
 
-// Make it executable
-if (import.meta.main) {
-  const { runPrd } = await import("gateproof/prd");
-  const result = await runPrd(prd);
-  if (!result.success) {
-    if (result.failedStory) console.error(`Failed at: ${result.failedStory.id}`);
-    process.exit(1);
-  }
-  process.exit(0);
-}
-```
-
-Each story references a gate file. The gate file uses gateproof's API:
-
-```typescript
-// gates/user-signup.gate.ts
-import { Gate, Act, Assert } from "gateproof";
-import { CloudflareProvider } from "gateproof/cloudflare";
-
-export async function run() {
-  const provider = CloudflareProvider({
-    accountId: process.env.CLOUDFLARE_ACCOUNT_ID!,
-    apiToken: process.env.CLOUDFLARE_API_TOKEN!,
-  });
-
-  const result = await Gate.run({
-    name: "user-signup",
-    observe: provider.observe({ backend: "analytics", dataset: "worker_logs" }),
-    act: [Act.browser({ url: "https://app.example.com/signup" })],
-    assert: [
-      Assert.noErrors(),
-      Assert.hasAction("user_created"),
-    ],
-  });
-
-  return { status: result.status };
-}
-```
-
-**gateproof does not own your PRD’s intent or state.** If you choose to use `gateproof/prd`, your PRD must match a small capsule shape (`stories[]` with `id/title/gateFile/dependsOn?/progress?`). The optional `progress` list is for your own tracking (or agent guidance); gateproof does not interpret or mutate it. Otherwise, orchestrate gates however you want — gateproof only cares about executing gate files.
-
-Stories execute in dependency order. The runner stops on first failure. Progress is not declared. It is proven.
-
-## How it works
-
-The PRD defines stories. Stories reference gate files. Gate files use gateproof's API. Gates can be enforced in CI before merge/deploy.
-
-**The sequence:** PRD story → gate file → gate execution → story marked "done" only when gate passes.
-
-**For agent iterations:** PRD → gate fails → agent fixes → gate re-runs → loop until pass.
-
-Run your PRD:
-
-```bash
-bun run prd.ts
-```
-
-Run agent iteration loop:
-
-```bash
-bash patterns/prd/agent-iteration-loop.sh
-```
-
-## Hardening `prd.ts` (recommended)
-
-Treat `prd.ts` like code: typecheck + validate before push + enforce in CI.
-
-- **Validate PRD**:
-
-```bash
-bun run prd:validate
-```
-
-- **Pre-push (default for everyone on your team)**: add to your `prepush` script (Husky calls it).
-
-```json
-{
-  "scripts": {
-    "prepush": "bun run typecheck && bun run prd:validate && bun test"
-  }
-}
-```
-
-- **CI**: run the validator before running PRD/tests.
-
-```yaml
-- name: Validate PRD
-  run: bun run prd:validate
-```
-
-- **Monorepo**: validate any PRD file by path.
-
-```bash
-bun run scripts/prd-validate.ts packages/api/prd.ts
+const result = await runPrd(prd);
+if (!result.success) process.exit(1);
 ```
 
-## Design notes
-
-- [Effect and Schema: Gateproof's Foundation](docs/effect-and-schema.md)
-
-## Writing good gates (agent-first)
-
-Gates can fail loudly. They can also pass on silence if you write weak assertions.
+## Assertions
 
-- **Always assert at least one positive signal**: `Assert.hasAction(...)` and/or `Assert.hasStage(...)`. If your backend can be silent, add an explicit “evidence must exist” custom assertion.
-- **Don’t rely on absence-only checks**: `Assert.noErrors()` alone can pass if you collect no logs.
-- **Treat observability as part of the system**: your confidence is bounded by what you can observe.
+`Assert.noErrors()`, `Assert.hasAction(name)`, `Assert.hasStage(name)`, `Assert.custom(name, fn)`, `Assert.authority(policy)`.
 
-## Limits / Non-goals
-
-- **Not a planner or orchestrator**: gateproof executes gates; your PRD (or CI) decides what to run and in what context.
-- **Not a truth oracle**: if your backend drops logs, a gate can be wrong. Gateproof can’t fix missing telemetry.
-- **Enforcement is external**: gateproof returns results; CI/CD decides whether to block merge/deploy.
-
-## Common objections (and answers)
-
-- **"Isn't this just E2E tests?"** Similar goal, different anchor. Gates are evidence-first (logs/telemetry + explicit assertions), not DOM-only. The contract is: observe → act → assert → evidence.
-
-- **"What about flaky telemetry?"** Gates don't fix missing telemetry. They make the dependency explicit. If your backend drops logs, a gate can be wrong — but you'll know immediately, not in production.
-
-- **"Isn't this overhead?"** It can be. The pitch isn't "gate everything." It's "gate the few transitions that are expensive to get wrong." Start with one critical path.
-
-- **"Will this lock us in?"** Gates are just TypeScript files. If you stop using gateproof, you keep the scripts and the intent. No vendor lock-in.
-
-## Quick Start
-
-The API is minimal: three concepts (Gate, Act, Assert). Here's a gate:
-
-```typescript
+```ts
 import { Gate, Act, Assert } from "gateproof";
 import { CloudflareProvider } from "gateproof/cloudflare";
 
@@ -283,157 +93,129 @@ const provider = CloudflareProvider({
 });
 
 const result = await Gate.run({
-  name: "api-health-check",
+  name: "checkout-flow",
   observe: provider.observe({ backend: "analytics", dataset: "worker_logs" }),
-  act: [Act.browser({ url: "https://my-worker.workers.dev" })],
-  assert: [Assert.noErrors(), Assert.hasAction("request_received")],
+  act: [Act.browser({ url: "https://app.example.com/checkout" })],
+  assert: [
+    Assert.noErrors(),
+    Assert.hasAction("checkout_started"),
+    Assert.custom("has-total", (logs) => logs.some(l => (l as { data?: { total?: number } }).data?.total > 0)),
+  ],
+  stop: { maxMs: 15_000 },
 });
-
 if (result.status !== "success") process.exit(1);
 ```
 
-This gate is a story verification. The PRD points at it.
+## Agent gates
 
-## Core API
-
-### Gate.run(spec)
-Run a gate. Returns a result with status, logs, and evidence.
-`spec.name` is optional metadata for labeling a gate.
-
-### Actions
-```typescript
-Act.exec("command")              // Run shell command
-Act.browser({ url, headless? })  // Browser automation (needs playwright)
-Act.wait(ms)                     // Sleep
-Act.deploy({ worker })           // Deploy marker
-```
+Spawn an AI agent in an isolated container, observe its NDJSON event stream, and assert what it's allowed to do.
 
-### Assertions
-```typescript
-Assert.noErrors()                // No error logs
-Assert.hasAction("name")         // Action was logged
-Assert.hasStage("worker")        // Stage was seen
-Assert.custom("name", fn)        // Custom: (logs) => boolean
-```
+```ts
+import { Gate, Act, Assert } from "gateproof";
+import { setFilepathRuntime, CloudflareSandboxRuntime } from "gateproof";
+import { getSandbox } from "@cloudflare/sandbox";
+
+// 1. Wire up your container runtime (once at startup)
+setFilepathRuntime(new CloudflareSandboxRuntime({
+  getSandbox: (config) => getSandbox(env.Sandbox, `agent-${config.name}`),
+}));
+
+// 2. Run the gate
+const container = await runtime.spawn({
+  name: "fix-auth",
+  agent: "claude-code",
+  model: "claude-sonnet-4-20250514",
+  task: "Fix the null pointer in src/auth.ts",
+});
 
-### Result
-```typescript
-{
-  status: "success" | "failed" | "timeout",
-  durationMs: number,
-  logs: Log[],
-  evidence: {
-    requestIds: string[],
-    stagesSeen: string[],
-    actionsSeen: string[],
-    errorTags: string[]
-  },
-  error?: Error
-}
+const observe = createFilepathObserveResource(container, "fix-auth");
+
+await Gate.run({
+  name: "fix-auth-bug",
+  observe,
+  act: [Act.wait(300_000)],
+  assert: [
+    Assert.noErrors(),
+    Assert.hasAction("commit"),
+    Assert.hasAction("done"),
+    Assert.authority({
+      canCommit: true,
+      canSpawn: false,
+      forbiddenTools: ["delete_file"],
+    }),
+  ],
+  stop: { idleMs: 5000, maxMs: 300_000 },
+});
 ```
 
-## PRD Runner
+`Assert.authority()` enforces governance policies against the agent's actual behavior — what it committed, spawned, and which tools it used.
 
-gateproof provides a PRD runner that executes stories in dependency order:
+## Writing good gates
 
-```typescript
-import { definePrd, runPrd } from "gateproof/prd";
+The hardest part of gateproof is not the library — it's writing gates that actually prove what you think they prove.
 
-const prd = definePrd({
-  stories: [
-    {
-      id: "story-1",
-      title: "First story",
-      gateFile: "./gates/story-1.gate.ts",
-    },
-    {
-      id: "story-2",
-      title: "Second story",
-      gateFile: "./gates/story-2.gate.ts",
-      dependsOn: ["story-1"],
-    },
-  ] as const, // keep story IDs as literal types
-});
+**A weak gate passes on silence.** If your system emits no logs and your only assertion is `Assert.noErrors()`, the gate passes vacuously. Nothing was tested. Use `requirePositiveSignal: true` on stories, or assert specific evidence (`Assert.hasAction`, `Assert.hasStage`).
 
-const result = await runPrd(prd);
-if (!result.success) {
-  console.error(`Failed at: ${result.failedStory?.id}`);
-  process.exit(1);
-}
-```
+**A good gate is falsifiable.** Ask: "what broken implementation would still pass this gate?" If the answer is "many," the gate is too weak. Tighten it until a broken system fails.
 
-The runner:
-- Validates dependencies (unknown IDs and cycles throw)
-- Topologically sorts stories by `dependsOn`
-- Executes gates in order
-- **Stops on first failure**
+**Start narrow, then widen.** One specific assertion that catches a real failure is worth more than ten vague ones. You can always add assertions later — you can't take back a false pass.
 
-## Plug Your Backend
+## The loop
 
-gateproof works with any observability backend. Just implement the `Backend` interface:
+Gate fails. Agent reads the failure evidence. Agent fixes code. Gate re-runs. Loop until pass.
 
-```typescript
-interface Backend {
-  start(): Effect.Effect<LogStream, ObservabilityError>;
-  stop(): Effect.Effect<void, ObservabilityError>;
-}
-```
+**Bring your own agent** — the loop takes any async function:
 
-See `patterns/` for examples including:
-- Cloudflare Analytics Engine
-- Cloudflare Workers Logs API
-- CLI Stream (local dev)
-- Custom backends
+```ts
+import { runPrdLoop } from "gateproof/prd";
 
-## Cloudflare Backends
+await runPrdLoop("./prd.ts", {
+  agent: async (ctx) => {
+    // ctx.failureSummary — what failed and why
+    // ctx.recentDiff    — recent git changes
+    // ctx.prdContent    — full PRD for context
+    // ctx.failedStory   — the Story object that failed
+    // ctx.signal        — AbortSignal for cancellation
 
-```typescript
-const provider = CloudflareProvider({ accountId, apiToken });
+    // Use any agent: Claude Code, Cursor, Codex, custom LLM wrapper
+    const result = await yourAgent.fix(ctx.failureSummary);
+    return { changes: result.files, commitMsg: "fix: resolve failing gate" };
+  },
+  maxIterations: 5,
+});
+```
 
-// Analytics Engine
-provider.observe({ backend: "analytics", dataset: "worker_logs" })
+Or use a pre-built agent:
 
-// Workers Logs API
-provider.observe({ backend: "workers-logs", workerName: "my-worker" })
+```ts
+import { runPrdLoop, createOpenCodeAgent } from "gateproof/prd";
 
-// CLI Stream (local dev)
-provider.observe({ backend: "cli-stream", workerName: "my-worker" })
+await runPrdLoop("./prd.ts", {
+  agent: createOpenCodeAgent({ apiKey: process.env.OPENCODE_ZEN_API_KEY }),
+  maxIterations: 7,
+});
 ```
 
-## Examples
-
-See `patterns/` for complete examples:
-- `patterns/basic/` - Basic usage patterns
-- `patterns/cloudflare/` - Cloudflare-specific patterns
-- `patterns/ci-cd/` - CI/CD integration
-- `patterns/advanced/` - Advanced patterns
-- `patterns/prd/` - PRD-as-code + agent iteration loop examples
-- `patterns/agent-first/` - Spec interview → PRD stories (agent-first)
-- `examples/hello-world-agent/` - Minimal agent with 5 tools + end-to-end gates
-
-Run the hello-world agent example (requires `OPENCODE_ZEN_API_KEY` and network access to `opencode.ai`):
+## Generate a PRD from plain language
 
 ```bash
-export OPENCODE_ZEN_API_KEY="your_key_here"
-bun run examples/hello-world-agent/prd.ts
+echo "Build a signup flow with email verification" | npx gateproof prdts --stdout
 ```
 
-## CI/CD
+## End-to-end CLI pipeline
 
-gateproof enforces gates in CI/CD. See `patterns/ci-cd/github-actions.ts` for examples.
+> Contributed by @grok
 
-Run your PRD in CI:
-
-```yaml
-- name: Run PRD
-  run: bun run prd.ts
+```bash
+# Natural language → prd.ts → agent loop
+echo "Build a signup flow with email verification" | npx gateproof prdts --out prd.ts
+npx gateproof smoke ./prd.ts
+bun run prd.ts
 ```
 
-## Requirements
+## Docs
 
-- Node.js 18+ or Bun
-- `playwright` (optional, for Act.browser)
-- Cloudflare credentials (for CloudflareProvider, or bring your own backend)
+Full documentation, tutorials, and API reference: [gateproof.dev/docs](https://gateproof.dev/docs)
 
 ## License
 

package/dist/act.d.ts

@@ -1,3 +1,26 @@
+/**
+ * Agent configuration for Filepath container execution.
+ *
+ * Specifies which agent runtime, model, and task to run inside
+ * an isolated container. The container communicates via NDJSON
+ * on stdout/stdin using the Filepath Agent Protocol (FAP).
+ */
+export interface AgentActConfig {
+    /** Display name for the agent (used in logs and tree UI) */
+    name: string;
+    /** Agent runtime: "claude-code" | "codex" | "cursor" | or a custom Docker image */
+    agent: string;
+    /** Model to use (e.g. "claude-sonnet-4-20250514", "gpt-4o") */
+    model: string;
+    /** Task description — sent as FILEPATH_TASK env var */
+    task: string;
+    /** Git repository URL to clone into /workspace */
+    repo?: string;
+    /** Additional environment variables for the container */
+    env?: Record<string, string>;
+    /** Timeout for the entire agent run in ms (default: 300_000 = 5 min) */
+    timeoutMs?: number;
+}
 export type Action = {
     _tag: "Deploy";
     worker: string;
@@ -14,6 +37,9 @@ export type Action = {
     command: string;
     cwd?: string;
     timeoutMs?: number;
+} | {
+    _tag: "Agent";
+    config: AgentActConfig;
 };
 export declare namespace Act {
     function deploy(config: {
@@ -29,5 +55,24 @@ export declare namespace Act {
         cwd?: string;
         timeoutMs?: number;
     }): Action;
+    /**
+     * Run an AI agent in a Filepath container.
+     *
+     * The agent executes in an isolated container with a git repo at /workspace.
+     * It communicates via the Filepath Agent Protocol (FAP) — NDJSON events on
+     * stdout that get mapped to Gateproof Log entries for gate assertions.
+     *
+     * @example
+     * ```ts
+     * Act.agent({
+     *   name: "fix-auth",
+     *   agent: "claude-code",
+     *   model: "claude-sonnet-4-20250514",
+     *   task: "Fix the authentication bug in src/auth.ts",
+     *   repo: "https://github.com/org/repo",
+     * })
+     * ```
+     */
+    function agent(config: AgentActConfig): Action;
 }
 //# sourceMappingURL=act.d.ts.map

package/dist/act.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"act.d.ts","sourceRoot":"","sources":["../src/act.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,MAAM,GACd;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAClC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GACrE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAC5B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAExE,yBAAiB,GAAG,CAAC;IACnB,SAAgB,MAAM,CAAC,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAEzD;IAED,SAAgB,OAAO,CAAC,MAAM,EAAE;QAC9B,GAAG,EAAE,MAAM,CAAC;QACZ,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,GAAG,MAAM,CAOT;IAED,SAAgB,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAEvC;IAED,SAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAEzF;CACF"}
+{"version":3,"file":"act.d.ts","sourceRoot":"","sources":["../src/act.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb,mFAAmF;IACnF,KAAK,EAAE,MAAM,CAAC;IACd,+DAA+D;IAC/D,KAAK,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAC;IACb,kDAAkD;IAClD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yDAAyD;IACzD,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,MAAM,GACd;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAClC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GACrE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAC5B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GACnE;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,cAAc,CAAA;CAAE,CAAC;AAE9C,yBAAiB,GAAG,CAAC;IACnB,SAAgB,MAAM,CAAC,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAEzD;IAED,SAAgB,OAAO,CAAC,MAAM,EAAE;QAC9B,GAAG,EAAE,MAAM,CAAC;QACZ,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,GAAG,MAAM,CAOT;IAED,SAAgB,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAEvC;IAED,SAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAEzF;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,SAAgB,KAAK,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAEpD;CACF"}

package/dist/act.js

@@ -21,5 +21,27 @@ export var Act;
         return { _tag: "Exec", command, cwd: opts?.cwd, timeoutMs: opts?.timeoutMs };
     }
     Act.exec = exec;
+    /**
+     * Run an AI agent in a Filepath container.
+     *
+     * The agent executes in an isolated container with a git repo at /workspace.
+     * It communicates via the Filepath Agent Protocol (FAP) — NDJSON events on
+     * stdout that get mapped to Gateproof Log entries for gate assertions.
+     *
+     * @example
+     * ```ts
+     * Act.agent({
+     *   name: "fix-auth",
+     *   agent: "claude-code",
+     *   model: "claude-sonnet-4-20250514",
+     *   task: "Fix the authentication bug in src/auth.ts",
+     *   repo: "https://github.com/org/repo",
+     * })
+     * ```
+     */
+    function agent(config) {
+        return { _tag: "Agent", config };
+    }
+    Act.agent = agent;
 })(Act || (Act = {}));
 //# sourceMappingURL=act.js.map