Behalf (PXP v0)

Behalf

Reference implementation of PXP v0, the Proxy Exchange Protocol: two AI proxies negotiate for two people, every claim is tagged stated / sourced / assumed, proxies escalate to their humans at a limit, and every agreement ships with a decision brief and a hash-chained ledger.

Based on the essay Agentic Proxies: When Humans Become Routing Nodes by Jules Nsenda.

• spec/ — a copy of the protocol (SPEC.md + JSON schemas). The canonical spec is JulesNsenda/pxp, published at https://julesnsenda.github.io/pxp/
• lib/pxp.js — protocol core: sealing, envelope enforcement, ledger
• lib/proxy.js — Claude-backed proxies
• lib/demo.js — scripted demo (hallucination cascade), runs with no API key
• lib/mcp.js — MCP endpoint at /mcp, so any MCP-capable agent can take a seat
• lib/auth.js, lib/http-auth.js — GitHub sign-in and agent keys
• lib/mail.js — email: one sendMail over a dev outbox or SMTP (lib/mail-dev.js, lib/mail-smtp.js). See MAIL.md
• index.js — the Node server (Node 20+). Its dependencies are pg, loaded only when DATABASE_URL is set, and nodemailer, loaded only when MAIL_TRANSPORT=smtp
• web/ — the pages:
  • Home (/)
  • Start (/start): create a room, then invite the other person
  • Room (/room/:id): instructions, then the conversation
  • Agreement (/brief/:id)
  • Connect (/connect): use your own AI agent, and create its agent key
  • Protocol (/spec)
• web/ui/ — the zero-dependency UI library; its living style guide is at /ui
• test/ — npm test (node:test). The Postgres tests run only when PG_TEST_URL is set

Config

ROOM_TTL_DAYS, DEMO_TTL_HOURS, MAX_ROOMS, TRUST_PROXY, SIGNIN, PER_USER_DAILY, GITHUB_BLOCKED_IDS, DRAIN_DEADLINE_MS, REQUIRE_DATABASE and the mail variables are strict: an invalid value stops the server at startup with BAD_<NAME>, and the log names the variable but never its value. ROOM_TTL_DAYS, DEMO_TTL_HOURS and MAX_ROOMS must be whole numbers from 1 up to 3650, 87600 and 1,000,000; PER_USER_DAILY from 1 to 1000. Each room also has an AI allowance of MAX_TURNS × 3 Claude calls, and drafting a card doesn't count toward it. A room that uses it up ends with no deal, like reaching the turn limit.

Startup refusals

The server stops at startup, and logs one line with a code, rather than run in a state that could lose data. If it stops, look for store.load_failed or app.init_failed in the log:

This covers the common cases, not every code. A StoreError is logged as store.load_failed with its code, and any other failure to start (including the config codes above) as app.init_failed. Both exit with status 1 before the server listens.

Agents and agent keys

An AI agent joins through MCP at /mcp. The seat link is its credential for everything in a room. With SIGNIN=github, creating a room also needs the person's agent key: sign in on /connect, create a key there, and give it to the agent as a header. For Claude Code:

claude mcp add --transport http behalf https://behalf.dropkit.sh/mcp --header "Authorization: Bearer YOUR_AGENT_KEY"

A key is shown once. It stops working after 90 days unused, or when you delete it on /connect. A browser session lasts 7 days without a visit, and 30 days at most.

Data

Without DATABASE_URL, state persists to DROP_DATA_DIR/rooms.json (or ./.data/rooms.json). Next to it the server can leave two kinds of recovery copies, and both can hold room content. If the file can't be parsed at all, it is moved aside as rooms.json.corrupt-<time> (the newest 5 are kept). If only some rooms fail to load, their original bytes are saved to rooms.json.partial-<time>, and those copies are never deleted, because each may be the only remaining copy of a room. Deleting a room from the server (eviction) doesn't delete these copies. Review them, and delete them yourself when they're no longer needed. Delete rooms.json to start empty.

With DATABASE_URL, everything lives in one table, behalf_records. Drop it to start empty.

• First start on Postgres. If the table is empty and DROP_DATA_DIR/rooms.json exists, the server copies every room and the day's usage into the table in one transaction, then renames the file to rooms.json.imported-<time>. Account records (users, sessions and agent keys) are imported too, along with the day's usage. Without DROP_DATA_DIR, the file it looks for is the local ./.data/rooms.json. A crash midway leaves the table empty, and the next start imports again. If the table already has data, the file is left alone and the server logs store.import_skipped. The .imported file keeps room content, seat tokens and any rooms that failed to load: check the import, then delete it once the deploy has soaked and rolling back is ruled out (see Rolling back). Minting a new agent key replaces the old one, so an imported key keeps working only until its owner makes a new one.
• Only one server at a time. The first server holds the database, and a second one waits and then stops with ELOCKED.
• Losing the database is fatal. If the connection drops, the server logs store.lock_lost; if a statement gets no answer at all, store.connection_lost. Either way it exits, and the platform restarts it from the database. Anyone mid-conversation then sees their room paused and presses Resume, and connected agents waiting on wait_for_turn get a dropped connection and must call again. If the database is down at startup, the server retries for about 45 seconds before it gives up.

On SIGTERM the server stops taking work, saves what is pending within DRAIN_DEADLINE_MS, and exits 0 (1 if the save failed). SIGINT drains the same way but always exits 130, whatever the save result. Docker stops an app with SIGTERM, but Drop's PM2 mode uses SIGINT (PM2's default), so under PM2 the exit code never says whether the last save worked. A failed final save is in the log instead: store.write_failed (Postgres) or store.save_failed (file store), and app.drain_timeout if the save hung. /health reports store (file or postgres) and storeOk.

Rolling back. A newer build can upgrade the stored format. An older build refuses data written by a newer schema and won't start, so keep a copy before an upgrade. An older build that predates sign-in loads a file with accounts but drops all accounts, sessions and agent keys on its next save, so after a rollback everyone signs in again and makes a new agent key. To go back from Postgres to the file store:

1. Stop the app, so nothing writes while you export.
2. Export the table: DATABASE_URL=... node scripts/export-rooms.js /path/to/rooms.json. It needs pg (npm ci), only reads, doesn't need the database lock, prints counts only, and refuses to overwrite a file. The result is a rooms.json in the file store's own format, with every room, the day's usage and the account records.
3. Put that file in DROP_DATA_DIR as rooms.json. Move any rooms.json already there aside first.
4. Deploy the old build.

rooms.json.imported-<time> is only the data as it was at the first Postgres start: rooms created since are only in the database, which is why you export. After restoring a .partial or .corrupt copy, clear sessions and agent keys, so nobody keeps access that was taken away.

Deploying on Drop

During a redeploy the new instance answers 503 "starting" until the old one stops and releases the database. Drop starts the new instance while the old one still serves, and stops the old one only once the new one answers HTTP. index.js therefore binds the port at once with a placeholder (503, {"code":"starting"}, and {"ok":false,"starting":true} on /health), then swaps in the real server when the store has loaded.

drop.yaml asks Drop for a Postgres database (it sets DATABASE_URL), sets SIGNIN: github and PUBLIC_URL, and declares the two GitHub secrets as required. Drop checks declared secrets before it starts the app: if one is missing, it holds the app in needs-config instead of letting it crash on start. DATABASE_URL is deliberately not declared: Drop sets it itself, and its redeploy check counts only secrets set by hand, so declaring it blocks every redeploy. Check /health after a deploy instead (step 5). drop.yaml also sets REQUIRE_DATABASE: "1": when Drop starts the app without DATABASE_URL, the process exits at once (BAD_REQUIRE_DATABASE), the readiness probe fails and the old version keeps serving, instead of an empty file store taking over.

1. Create a GitHub OAuth app. Its callback URL must be exactly https://behalf.dropkit.sh/auth/github/callback (PUBLIC_URL + /auth/github/callback).
2. In the Drop dashboard, set GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET, ANTHROPIC_API_KEY, ROOM_PASSCODE and any limits. Also set TRUST_PROXY for how Drop connects to the app. Under PM2 isolation, Drop's Caddy reaches the app over loopback (localhost:PORT), so set TRUST_PROXY=loopback. Under Docker isolation the port is published on the host's loopback, but the app sees the connection from the Docker bridge, a private address: keep the default private. (loopback under Docker would ignore X-Forwarded-For, and every visitor would share one address for the per-address limits.)
3. Any dashboard value overrides drop.yaml. Check SIGNIN and PUBLIC_URL in the dashboard before you redeploy: remove them, or set them to the drop.yaml values (github and https://behalf.dropkit.sh). A leftover SIGNIN=off keeps sign-in off, and a stale PUBLIC_URL breaks the GitHub callback.
4. Redeploy. On first start the server imports rooms.json (see Data). Keep rooms.json.imported-<time> until the deploy has soaked and rolling back is ruled out, then delete it: it holds room content and seat tokens.
5. Check /health: store must be postgres and storeOk true. store: file means the database wasn't provisioned: look for store.file_fallback in the log. Also check that /api/config shows signin as github.