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/ai-access.js — "Use our AI" access: who may spend the built-in Claude (lib/durable.js is the save bookkeeping it shares with lib/auth.js)
• 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
  • Admin (/admin): the owner approves "Use our AI" requests
  • 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, ADMIN_GITHUB_IDS, ADMIN_EMAIL, 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.

Inviting by email

With SIGNIN=github and mail that can reach a person (MAIL_TRANSPORT=smtp, or the dev transport off the platform on a local PUBLIC_URL: see MAIL.md), the invite step of /start has an optional "Their email" field. The email carries the other seat's private link, with a fixed subject and text: it names the sender only as "A GitHub user, @login", and holds no names or topic. Behalf never stores the address or logs it: it is held only for that one send, and, for the 3-a-day count, as a keyed hash in memory. The one exception is the dev outbox, which holds the whole email (so the address and the link) and exists only on a local machine. Limits: 3 invites per room, 10 per person and 50 per day across everyone (admins and people with "Use our AI" access don't count toward the 50), and 3 a day to the same address (the usual spellings of one mailbox, such as [email protected] and [email protected], share it). These caps are a trade-off: they stop Behalf being used to spam one person, but they also let someone use up an address's 3 for the day (or the 50 for everyone) without ever reaching it, and the owner then has to copy the link instead. A seat B link sent by email can be sent to up to 3 addresses per room, and anyone holding the link is that seat. Past a limit the page says so and the owner can copy the link instead. Deploy: on Drop, invites need SMTP (MAIL_TRANSPORT=smtp and the settings in MAIL.md). Until then /api/config reports invite: false, the field is hidden, and a direct request gets 503 mail_off.

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. /key is the short link to that panel (it redirects to /connect#agent-keys, and answers 404 with sign-in off), and the agent's refusal and instructions name it as <PUBLIC_URL>/key. For Claude Code:

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

A person can hold up to 10 keys at once, one for each app or device. Each is named when it is created ("Which app is this for?", optional, up to 40 characters, and not the same as the name of another key of yours), is shown once, and is deleted on its own on /connect; creating a new key ends no other, so to change an app's key you create a new one, then delete the old one. The list shows each key's name (or "Agent key (created , <first 4 characters of the kid>)" when it has none, so two made on one day differ), when it was made and when it was last used. A key has a public id, the kid: the first 12 hex characters of the SHA-256 of kid: plus its stored id. The kid is worked out whenever it is needed and is never stored, and the delete button names a key by it. A key stops working after 90 days unused, or when you delete it, and a key that has been idle that long no longer counts towards the 10. A browser session lasts 7 days without a visit, and 30 days at most.

The page uses POST /api/me/agent-key ({ "name": "..." }, optional; 201 with the key and its kid, 409 key_limit at 10 keys, 400 for a name that cannot be kept) and POST /api/me/agent-key/revoke ({ "kid": "..." }; 204, or 503 while saving is failing, and a retried delete answers 503 again until it is saved). GET /api/me lists the keys as agentKeys, newest first, with no secret in them.

"Use our AI" access

With SIGNIN=github, there are two separate kinds of access. An agent key connects a person's own AI (an MCP client). "Use our AI" is permission to spend the hosted built-in Claude, which costs the owner money: a built-in seat, drafting a card and the authority audit in the agreement. Taking a seat with a seat link stays keyless.

• Anyone signed in can open a room where both sides bring their own AI. Opening a room with a built-in seat needs access, from the web or from MCP (counterpart_proxy: "builtin"): without it the answer is 403 ai_access, naming <PUBLIC_URL>/start. A room also remembers whether its opener had access when it was made (room.ai): a room opened without it can never draft a card or run the audit, whatever happens to the opener later. Rooms made before this existed count as allowed.
• On /start a person without access sees a "Use our AI" block: a short note and a Request access button. A request is none, then requested; the admin decides.
• Granting access. Set ADMIN_GITHUB_IDS to your numeric GitHub id (https://api.github.com/users/<login> shows it as id) in the Drop dashboard and restart. Sign in, open /admin (the account menu shows an Admin link) and press Grant, Deny or Reset on a request. A decision is saved before the page says it is done, and is refused (503) while saving is failing; a grant counts only once it is saved. Each decision is stored with the id of the admin who made it and logged as one event, ai.granted, ai.denied or ai.reset, with no fields: the log has no user id and never the note. To anyone who is not an admin, /api/admin/ai-access answers 404, whatever they send.
• Requests are limited to 5 per person per 10 minutes, and 500 may wait at once (requests_full). A request note is plain text of at most 280 characters, shown to you as quoted text and never as a link; it is never logged.
• Existing users lose the built-in AI at the deploy that adds this, until you grant them (admins keep it). Rooms already running with built-in seats keep going, and a deny does not stop rooms that are already open: each one can spend at most its own allowance (MAX_TURNS × 3 calls), and no new room with a built-in seat can be opened.
• Any build without the aiaccess kind keeps no grants: see Rolling back.

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). An imported key keeps working, and shows as "Agent key (created , )" until its owner deletes it.
• 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, agent keys and "Use our AI" grants on its next save. More exactly, any build that does not know the aiaccess kind drops the grants from a file store on its next write; on Postgres the grant rows stay in the table, and come back when a newer build starts again. After a rollback everyone signs in again and makes a new agent key. An older build that has accounts but predates named keys keeps only the newest key per user (it drops the rest when it loads them), and its connect page makes a new key replace the old one; the names are not read, and the other keys are gone after the next save. 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. If the build you deploy defaults REQUIRE_DATABASE to 1 on Drop, set REQUIRE_DATABASE=0 in the dashboard, or it refuses to start without the database. Remove it when you go back to Postgres.
5. 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). REQUIRE_DATABASE is on by default whenever DROP_DATA_DIR is set, and drop.yaml sets it to "1" as well. Don't set it to 0 in the dashboard (dashboard values override drop.yaml) except to run on the file store on purpose, as in Rolling back. 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, ADMIN_GITHUB_IDS (your numeric GitHub id: without it nobody can grant "Use our AI" and the server logs app.no_admins) and any limits. ROOM_PASSCODE is not used with sign-in on. 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.