# Project export: plsbro

This document was generated by HackStack to give an AI agent context about a hackathon project. Sections are labeled with their provenance; content marked as truncated was cut to keep this document small.

## Project metadata

- Hackathon: OpenAI Build Week
- Tagline: Don’t just tell an AI agent please, bro and hope. PLSBRO gives every task a contract, sandbox, budget, verification, and audit trail.
- Devpost: https://devpost.com/software/plsbro
- GitHub: https://github.com/jaydenjk0329/plsbro-h1-demo
- Demo: https://plsbro-h1-demo.vercel.app/demo
- Video: https://www.youtube.com/embed/RArYzuPSoWY?enablejsapi=1&hl=en_US&rel=0&start=&version=3&wmode=transparent
- Team: 1 GitHub contributor(s) — Jayden Kim (5 commits)

## Devpost submission (written by the team)

### Inspiration

Most AI-agent products start with a request like “please do this,” then ask us to trust whatever happens next. As agents gain access to files, APIs, money, and production systems, prompt quality is no longer enough. Users need to know what an agent is allowed to do, what data it can access, how much it can spend, what evidence proves the work was completed, who verified the result, and whether the execution environment was destroyed afterward. PLSBRO turns those questions into an explicit, enforceable task contract before execution begins.

### What it does

Our demonstration runs a platform-owned CSV-cleanup agent. Before execution, the user sees and approves: The fixed synthetic input Permitted operations Declared output artifacts Deterministic success criteria A deny-all network policy A one-model-call ceiling A $0.00220000 budget reservation The agent runs inside an isolated Vercel Sandbox using a two-stage Python runner: Inspect the task and request one structured column-mapping decision. Execute the approved transformation and produce the declared artifacts. The sandbox has no OpenAI key, no secrets, and no external network access. The model request is handled by the trusted control plane, which sends only CSV headers and platform-owned metadata—not private row values—to the OpenAI Responses API. The agent produces: cleaned.csv reconciliation.json A separate TypeScript verifier then checks that: Required columns are present Status values are normalized Duplicate rows were removed Input and output counts reconcile The files are valid UTF-8 Only declared artifacts were created The output matches the task contract The result is accepted only after those checks pass. How I built it PLSBRO combines: Next.js and TypeScript for the control plane and interface Python 3.13 for the sandbox runner Vercel Sandbox for isolated execution OpenAI Responses API with strict structured output JSON Schema and versioned contracts Integer-based budget accounting Independent artifact verification Hash-linked platform audit evidence Docker-backed runtime and protocol tests GitHub Actions for Linux integration and end-to-end validation The wider foundation also includes transactional lifecycle auditing, leased work execution, retry recovery, stale-worker rejection, idempotency, artifact checksums, and restricted runtime images. The demo intentionally uses a fixed synthetic CSV instead of arbitrary uploads. This makes the workflow safe, repeatable, and objectively verifiable while demonstrating the underlying execution architecture. Live result The successful browser-based execution produced: One actual model call Zero simulated model calls 106 input tokens 32 output tokens A verified cleaned CSV Confirmed sandbox deletion A complete audit timeline At published rates of $1 per million input tokens and $6 per million output tokens: Input cost: 106 × $1 ÷ 1,000,000 = $0.000106 Output cost: 32 × $6 ÷ 1,000,000 = $0.000192 Total measured cost: $0.000298 This stayed well below the reserved maximum of $0.00220000. Challenges The hardest part was not getting the model to clean a CSV. The difficult part was proving that the surrounding system behaved correctly. I had to separate: Agent-generated artifacts from platform-generated evidence Model generation from deterministic verification Sandbox permissions from control-plane permissions Simulated results from live results Budget reservation from actual cost reconciliation Sandbox cleanup also had to occur on success, failure, malformed evidence, timeout, and interruption paths. Another major challenge was maintaining parity across macOS development, Linux containers, and GitHub-hosted CI. Differences in filesystem permissions, process reaping, command behavior, runtime environment variables, and Node installation layouts exposed assumptions that local tests did not initially reveal. Deployment introduced additional lessons around secret handling, access-code protection, disabled-first releases, restricted API keys, and kill-switch restoration. PLSBRO defaults to live execution being disabled and enables it only during controlled demonstration windows. What I learned The largest lesson was that trustworthy agents require more than a capable model. A useful trust layer needs: A specification before execution Least-privilege isolation during execution Bounded spending and provider access Independent verification after execution Auditable evidence for every important transition Fail-safe cleanup on every terminal path I also learned that “the tests are green” is not the same as “the boundary is proven.” Adversarial review repeatedly found cases where evidence could be ambiguous, cleanup could fail, or one operating system behaved differently. Treating those findings as part of the design process made the final system materially stronger.

### What's next

The CSV workflow is a focused demonstration of a broader idea. The next step is to generalize the contract, execution, verification, and audit layers so developers can safely define additional workflows. Arbitrary uploads, external tools, and marketplace distribution would come only after the corresponding privacy, permission, and verification boundaries are proven. PLSBRO turns autonomous work from a black box into a bounded, verifiable process—from an explicit contract, to isolated execution, to an audit-ready result. See every boundary. Trust every result.

## README (from the GitHub repository)

# PLSBRO — Trusted Agent Execution Demo

PLSBRO is a managed operating layer for agent-completed work. This standalone OpenAI Build Week demo proves a narrow developer-tools flow:

```text
synthetic CSV
→ visible task contract
→ human approval
→ deny-all Vercel Sandbox
→ platform-owned Python runner
→ one managed GPT-5.6 Luna mapping decision
→ deterministic transformation and verification
→ artifacts, measured usage, and an audit receipt
```

This repository is a hackathon demonstration, not production sandbox certification or a complete marketplace.

## Our demo

- A polished `/demo` contract-review and approval experience
- One bounded sandbox and a two-stage Python runner
- A privacy-validated `column_mapping_v1` model request
- Deterministic success and budget-blocked modes
- Independent verification, usage accounting, and an audit timeline
- Synthetic input and expected output fixtures

The sandbox has deny-all networking and never receives an OpenAI API key. The trusted server performs the model call and writes the validated response back to the sandbox. The agent produces `cleaned.csv` and `reconciliation.json`; PLSBRO independently produces verification, usage evidence, and `audit-receipt.json`.

## How Codex and GPT-5.6 were used

### Codex

Codex served as the engineering collaborator. It helped translate the product specification into the architecture and implementation, build the interface and trusted control-plane flow, develop the two-stage Python runner, create security and replay tests, document the system, and remediate independent review findings. Product decisions, external-service authorization, and acceptance remained human-controlled. Codex is not the runtime agent and does not approve its own output.

### GPT-5.6 Luna

GPT-5.6 Luna provides one bounded semantic decision in an enabled live-success run: mapping an ambiguous source header such as `Cust. Co.` to `company_name`. The trusted control plane makes at most one Responses API call with:

- Structured `column_mapping_v1` output
- `store: false`
- At most 1,000 input tokens and 200 output tokens
- A maximum pre-call reservation of `$0.00220000`
- Headers and platform-owned schema metadata only—never CSV row values

Deterministic platform verification remains authoritative. A model response cannot declare its own output verified.

## Architecture

```text
Browser
  │ contract approval + private access code
  ▼
Next.js trusted control plane
  ├─ validates permissions, privacy, and budget
  ├─ creates one deny-all Vercel Sandbox
  ├─ runs: python runner.py request
  ├─ validates mapping-request.json
  ├─ calls GPT-5.6 Luna once through Responses API
  ├─ writes mapping-response.json
  ├─ runs: python runner.py execute
  ├─ independently verifies declared artifacts
  └─ returns result, usage, cost, and audit receipt
```

The Vercel Sandbox uses its built-in Python 3.13 runtime, one vCPU, a maximum 60-second duration, and no network access. Only synthetic fixture data is supported.

## Run locally without external services

Requirements: Node.js 24.18.0, pnpm 11.13.1, and Python 3.13.

```bash
corepack enable pnpm
pnpm install --frozen-lockfile
cp .env.example .env.local
```

Set these private local values in `.env.local`:

```text
H1_DEMO_ENABLED=true
H1_DEMO_ADAPTER=fake
H1_DEMO_ACCESS_CODE=<a long private value>
```

Then run:

```bash
pnpm dev
```

Open `http://localhost:3000/demo`. Fake results are explicitly labeled `simulated`; they report zero actual calls and zero actual cost and cannot be presented as live evidence.

## Validate

```bash
pnpm check
```

This runs formatting, lint, TypeScript checks, unit and route tests, the Python runner tests, and a production build. No provider credentials or external calls are required.

## Synthetic fixture

- [`demo-assets/input.csv`](demo-assets/input.csv)
- [`demo-assets/contract.json`](demo-assets/contract.json)
- [`demo-assets/expected-cleaned.csv`](demo-assets/expected-cleaned.csv)
- [`demo-assets/runner.py`](demo-assets/runner.py)

## Deployment safety

Live execution is intentionally fail-closed. A production deployment requires `H1_DEMO_ADAPTER=live`, an explicit server-side enable switch, a long private access code, an OpenAI project restricted to `gpt-5.6-luna`, and Vercel runtime OIDC supplied by Vercel. Never commit credentials, `.env.local`, `.vercel`, live access instructions, or provider evidence.

The public repository contains no live credential or access code. Live execution should remain disabled outside a supervised judging window.

## Explicit exclusions

No external agent publishing, custom OCI images, VCR, Stripe, marketplace listings, payouts, stored balances, customer data, multi-agent delegation, or production conformance claims are included.

## License

MIT — see [LICENSE](LICENSE).


## Detected evidence (automated analysis)

Indexed codebase: 37 recognized source files, 257 KB.
- CSS (language) — detected in the code
- Next.js (technology) — detected in the code
- OpenAI (technology) — detected in the code
- Python (language) — detected in the code
- React (technology) — detected in the code
- TypeScript (language) — detected in the code
- Docker (technology) — claimed on Devpost, not found in the code
- Vercel (technology) — claimed on Devpost, not found in the code

## Codebase structure (from repository index)

### Files (45 of 45)

```
.env.example
.github/workflows/ci.yml
.gitignore
app/api/demo/run/route.test.ts
app/api/demo/run/route.ts
app/demo/demo-client.tsx
app/demo/demo.module.css
app/demo/page.tsx
app/globals.css
app/layout.tsx
app/page.tsx
demo-assets/contract.json
demo-assets/expected-cleaned.csv
demo-assets/input.csv
demo-assets/runner.py
demo-assets/test_runner.py
eslint.config.mjs
lib/demo/audit.ts
lib/demo/contract.ts
lib/demo/fake-gateway.ts
lib/demo/fake-sandbox.ts
lib/demo/gateway.ts
lib/demo/handler.test.ts
lib/demo/handler.ts
lib/demo/live-gateway.ts
lib/demo/live-sandbox.ts
lib/demo/money.test.ts
lib/demo/money.ts
lib/demo/orchestrator.test.ts
lib/demo/orchestrator.ts
lib/demo/presentation.test.ts
lib/demo/presentation.ts
lib/demo/protocol.test.ts
lib/demo/protocol.ts
lib/demo/sandbox.test.ts
lib/demo/sandbox.ts
lib/demo/verifier.ts
LICENSE
next-env.d.ts
next.config.ts
package.json
pnpm-workspace.yaml
proxy.ts
README.md
tsconfig.json
```

### Dependencies

- package.json: @types/node@24.3.0, @types/react@19.2.14, @types/react-dom@19.2.3, @vercel/sandbox@2.7.0, eslint@9.34.0, eslint-config-next@16.2.10, next@16.2.10, openai@6.48.0, prettier@3.9.5, react@19.2.7, react-dom@19.2.7, typescript@5.9.2, vitest@3.2.6

### Recent commits (newest first)

- Update README.md
- Update README.md
- Merge pull request #1 from jaydenjk0329/codex/fix-demo-ci
- ci: enable pnpm after Node setup
- feat: publish PLSBRO trusted agent demo

## Key source files (fetched from GitHub, selected and truncated for size)

### package.json

```
{
  "name": "plsbro-h1-demo",
  "version": "1.0.0",
  "private": true,
  "packageManager": "pnpm@11.13.1",
  "engines": {
    "node": "24.18.0"
  },
  "scripts": {
    "build": "next build",
    "check": "pnpm format:check && pnpm lint && pnpm typecheck && pnpm test && pnpm python:test && pnpm build",
    "dev": "next dev",
    "format:check": "prettier --check .",
    "lint": "eslint .",
    "python:test": "python3 -m unittest demo-assets/test_runner.py",
    "start": "next start",
    "test": "vitest run",
    "typecheck": "tsc --noEmit"
  },
  "dependencies": {
    "@vercel/sandbox": "2.7.0",
    "next": "16.2.10",
    "openai": "6.48.0",
    "react": "19.2.7",
    "react-dom": "19.2.7"
  },
  "devDependencies": {
    "@types/node": "24.3.0",
    "@types/react": "19.2.14",
    "@types/react-dom": "19.2.3",
    "eslint": "9.34.0",
    "eslint-config-next": "16.2.10",
    "prettier": "3.9.5",
    "typescript": "5.9.2",
    "vitest": "3.2.6"
  }
}

```

### app/page.tsx

```typescript
import { redirect } from "next/navigation";

export default function Home() {
  redirect("/demo");
}

```

### app/layout.tsx

```typescript
import type { Metadata } from "next";
import "./globals.css";

export const metadata: Metadata = {
  title: "PLSBRO Trusted Agent Execution Demo",
  description:
    "A judge-facing demonstration of approved, isolated, metered, and verified agent work.",
};

export default function RootLayout({
  children,
}: Readonly<{ children: React.ReactNode }>) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}

```

### app/demo/page.tsx

```typescript
import type { Metadata } from "next";
import Link from "next/link";

import { DEMO_CONTRACT, DEMO_INPUT_CSV } from "@/lib/demo/contract";

import { DemoClient } from "./demo-client";
import styles from "./demo.module.css";

export const metadata: Metadata = {
  title: "Trusted Agent Execution Demo · PLSBRO",
  description:
    "A judge-facing demonstration of approved, isolated, metered, and verified agent work.",
};

export default function DemoPage() {
  return (
    <main className={styles.page}>
      <div className={styles.ambient} aria-hidden="true" />
      <header className={styles.header}>
        <Link className={styles.brand} href="/">
          <span className={styles.brandMark}>P</span>
          <span>PLSBRO</span>
        </Link>
        <span className={styles.hackathonBadge}>OpenAI Build Week · H1</span>
      </header>

      <section className={styles.hero}>
        <div>
          <p className={styles.kicker}>Trusted agent execution</p>
          <h1>
            See every boundary.
            <br />
            Trust every result.
          </h1>
          <p className={styles.heroCopy}>
            Approve a visible task contract, run a platform-owned agent in one
            deny-all sandbox, and inspect the verification, usage, and audit
            evidence behind the result.
          </p>
        </div>
        <div className={styles.boundaryCard}>
          <span className={styles.boundaryLabel}>Execution boundary</span>
          <div className={styles.boundaryRow}>
            <span>Browser</span>
            <i>approval</i>
            <span>Control plane</span>
            <i>files</i>
            <span>Sandbox</span>
          </div>
          <div className={styles.policyStrip}>
            <span className={styles.pulse} /> Network: deny-all
            <span>1 sandbox</span>
            <span>≤ 1 model call</span>
          </div>
        </div>
      </section>

      <div className={styles.notice} role="note">
        <strong>Hackathon demonstration</strong>
        <span>
          Platform-owned runner · synthetic data · not production sandbox
          certification
        </span>
      </div>

      <DemoClient contract={DEMO_CONTRACT} inputCsv={DEMO_INPUT_CSV} />

      <footer className={styles.footer}>
        <span>PLSBRO Developer Tools</span>
        <span>Specification → execution → verification</span>
      </footer>
    </main>
  );
}

```

### app/api/demo/run/route.ts

```typescript
import type { DemoMode } from "../../../../lib/demo/contract";
import { handleDemoRun } from "../../../../lib/demo/handler";
import type { DemoDependencies } from "../../../../lib/demo/orchestrator";

export const runtime = "nodejs";
export const dynamic = "force-dynamic";
export const maxDuration = 120;

class ForbiddenModelGateway {
  async mapColumn(): Promise<never> {
    throw new Error("demo.provider_call_forbidden");
  }
}

async function dependenciesFor(mode: DemoMode): Promise<DemoDependencies> {
  const adapter = process.env.H1_DEMO_ADAPTER;
  const production =
    process.env.NODE_ENV === "production" || process.env.VERCEL === "1";
  if (production && adapter !== "live")
    throw new Error("demo.live_adapter_required");
  if (adapter === "fake") {
    if (production) throw new Error("demo.fake_adapter_forbidden");
    const [{ FakeDemoSandboxFactory }, { FakeDemoModelGateway }] =
      await Promise.all([
        import("../../../../lib/demo/fake-sandbox"),
        import("../../../../lib/demo/fake-gateway"),
      ]);
    return {
      sandboxFactory: new FakeDemoSandboxFactory(),
      modelGateway: new FakeDemoModelGateway(),
    };
  }
  if (adapter !== "live") throw new Error("demo.invalid_adapter");
  const [{ LiveDemoSandboxFactory }, { LiveDemoModelGateway }] =
    await Promise.all([
      import("../../../../lib/demo/live-sandbox"),
      import("../../../../lib/demo/live-gateway"),
    ]);
  return {
    sandboxFactory: new LiveDemoSandboxFactory(),
    modelGateway:
      mode === "budget_denied"
        ? new ForbiddenModelGateway()
        : new LiveDemoModelGateway(process.env.OPENAI_API_KEY ?? ""),
  };
}

export function POST(request: Request): Promise<Response> {
  return handleDemoRun(request, {
    accessCode: process.env.H1_DEMO_ACCESS_CODE ?? "",
    executionEnabled: process.env.H1_DEMO_ENABLED === "true",
    dependenciesFor,
  });
}

```

### pnpm-workspace.yaml

```yaml
overrides:
  postcss: 8.5.10

allowBuilds:
  esbuild: true
  sharp: true
  unrs-resolver: true

```

### next.config.ts

```typescript
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  outputFileTracingIncludes: {
    "/api/demo/run": ["./demo-assets/**/*"],
  },
};

export default nextConfig;

```

### next-env.d.ts

```typescript
/// <reference types="next" />
/// <reference types="next/image-types/global" />
import "./.next/types/routes.d.ts";

// NOTE: This file should not be edited
// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

```

### proxy.ts

```typescript
import { NextResponse, type NextRequest } from "next/server";

function isDemoPath(pathname: string): boolean {
  return (
    pathname === "/demo" ||
    pathname.startsWith("/demo/") ||
    pathname === "/api/demo/run" ||
    pathname.startsWith("/_next/") ||
    pathname === "/favicon.ico"
  );
}

export function proxy(request: NextRequest) {
  if (request.nextUrl.pathname === "/")
    return NextResponse.redirect(new URL("/demo", request.url));
  if (isDemoPath(request.nextUrl.pathname)) return NextResponse.next();
  return new NextResponse(null, {
    status: 404,
    headers: { "cache-control": "no-store" },
  });
}

export const config = {
  matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
};

```

### app/globals.css

```css
:root {
  color-scheme: dark;
  font-family: ui-sans-serif, system-ui, sans-serif;
  background: #090b10;
  color: #f5f7fa;
}
* {
  box-sizing: border-box;
}
body {
  margin: 0;
  min-height: 100vh;
}
main {
  max-width: 72rem;
  margin: 0 auto;
  padding: 4rem 1.5rem;
}
.eyebrow {
  color: #83e6c4;
  letter-spacing: 0.12em;
  text-transform: uppercase;
  font-size: 0.75rem;
}
.panel {
  margin-top: 2rem;
  border: 1px solid #29313d;
  border-radius: 1rem;
  padding: 1.5rem;
  background: #10141b;
}
a {
  color: inherit;
}

```

[26 more indexed source files omitted to keep this export small. The full file list is in the Codebase structure section above.]