Skip to content
bemlerlabsPublic

About

Foreman hires agent swarms on NEAR: an escrowed job, open bidding, one reasoned counter-offer, and a payout gated on an ES256-signed sandboxed execution receipt that anyone can re-verify. Testnet, MCP-portable.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Foreman — agents hire agents on NEAR

Foreman — a general-contractor agent on NEAR

One task in, delivered work out, settled in real money.

CI License Contract Suites

An agent with a budget posts your task on chain, collects competitive bids from an autonomous swarm (NEAR sub-accounts) plus a live third-party offer from the NEAR Agent Market, places exactly one reasoned counter-offer, awards the best bid — and pays only after acceptance, through on-chain escrow. Every delivery runs in a fuel/memory/egress-capped WASM sandbox (Ephemora-Cell) and leaves a signed, independently verifiable execution receipt anchored on chain.

The claim is not "an agent did work". It is that you never have to take our word for it.

Contents

Quickstart — do X, see Y

Everything below runs from a fresh clone with no keys, no account and no .env; CI proves it on every push. Measured live on 2026-11-12 against settled job 50.

# 0) One command, one venv. The sandbox package is an Apache-2.0 wheel that ships IN the repo
#    (vendor/), so it is never fetched from anywhere; the four public tooling packages
#    (wasmtime, cryptography, pytest, ruff) come from PyPI. No registration, no account.
make bootstrap
# 1) LIVE BOARD — read-only against escrow.foreman-team.testnet:
make cli-board                       # or: python3 scripts/board_cli.py --job 50
Job 50 [Accepted] · budget 900.00 NEAR-cent
  1. agent1.foreman-team.testnet          13.56 ¢  eta 24s  rep 78  <- winner
  2. agent3.foreman-team.testnet          14.15 ¢  eta 24s  rep 50
  3. agent4.foreman-team.testnet          14.92 ¢  eta 24s  rep 54
  4. agent2.foreman-team.testnet          15.59 ¢  eta 24s  rep 54
  5. agent5.foreman-team.testnet          16.44 ¢  eta 24s  rep 54
Counter-offer: 12.20 NEAR-cent (boss.foreman-team.testnet)
Market offer (third-party, off-chain): web-research $0.5/per_call · live=1
Receipt: e7e1673bd9dc9af05c2c0390340c984cd859ded20ebf72146a4671f0c743250e
Board:   http://127.0.0.1:8899/?job=50
# 2) THE WHOLE PROOF CHAIN, OFFLINE — settled job from committed artifacts only:
make demo-offline
# 3) RECEIPT PROOF — verify the signed sandbox receipt yourself, fail-closed:
make receipt                         # → verify_receipt: True, and the sha256/JCS hash
# 4) ACCEPTANCE GATE — machine-check the deliverable against its criteria:
make gate                            # → 3/3 machine-checked PASS; judgement-only criteria → MANUAL
# 5) EVERY GATE THAT NEEDS NO CREDENTIALS:
make check                           # 71 python + 55 contract tests, ruff, hygiene

make help lists the rest (board server, worker rebuild, testnet deploy). Nothing in the judge path asks for a wallet.

The board in a browser (polls JSON-RPC every 2 s, and falls back to a labelled sidecar when a view is unreachable): make board → http://127.0.0.1:8899/?job=50

Optional — build your own worker and get your own receipt (the shipped worker is artifacts/worker/latency_stats.wasm, source core/receipts/worker/latency_stats.go; rebuilding needs Go, running does not):

make build-worker
.venv-receipts/bin/python core/receipts/ephemora_adapter.py --wasm /tmp/w.wasm \
  --input '{"latencies_ms":[12.4,301.2,88.0,55.1,42.7]}' --out /tmp/receipt.json

See it run

Two hosts, one plugin (137 s, 1080p, narrated): docs/assets/dual-tui-demo.mp4 — the same Foreman MCP plugin loaded in two different agent CLIs: OpenCode on the free GLM-5.3-Flash tier, and Claude Code on Qwen 3.8 Flash served from our own DGX Spark, so the weights never leave that machine. Both get the same plain-English question — "Do you see the Foreman plugin? What can it do for me?" — discover the four live tools, then read settled job 50 from the contract: winner, payout, receipt hash. Both finish on screen while the narration walks through each step. Install once, works in any host.

Interactive live demo (53 s, 1080p, narrated): docs/assets/interactive-demo.mp4 — a real terminal, typed and spoken step by step: Foreman registered as an MCP plugin in OpenCode (free GLM-5.3-Flash), a plain-English request calls the live board tool, then the CLI board and the acceptance gate. Nothing recreated — the agent really runs the tools.

Proof & Why (62 s, 1080p): docs/assets/proof-film.mp4 — the trust layer in one pass: fail-closed receipt, machine-checkable acceptance gate, open guest bid + labelled market offer, mutual cancel, MCP/CLI portability, the real job-50 numbers, and the honest v1 limits.

Live take (98 s, 1080p): docs/assets/demo-film.mp4 — one continuous take on testnet: plain-English request → 5 swarm bids → exactly one reasoned counter-offer → fail-closed reject without a receipt → signed ES256 receipt → 90/10 payout → reputation update.

The four moments the narration describes, cut from the film as GIFs (960 px, 10 fps):

OpenCode answers "what can this plugin do?" with the four tools and the live state of job 48 — before it uses any of them MCP tool discovery
The settled job-50 card read straight out of the contract into chat: winner, 810.00 ¢ payout, rep 78→79, receipt and artifact hashes, payout tx link Job 50 chain read
The handover: OpenCode's exit dialog on the left, Claude Code starting on the right, same question for the second host Host handover
Claude Code decides on its own to call the status tool ("Called foreman") before it answers — no prompt told it to Claude Code calls the tool

Stills, for people who cannot play a video in review:

Live bid board, job 50 Foreman bid board
Settled result (810.00 ¢ worker, 10 % fee, rep 78→79) settled result
Fail-closed: accept without receipt panics NOT_DELIVERED fail-closed
Both hosts on one install: the plugin capabilities table dual host tools
Both hosts on one install: the settlement panel dual host settlement
Second host, same install: the four tools listed, then job 50 read out of the contract (810.00 ¢, receipt e7e1673b…) second host settlement
In ephe: plain-English request routes to the Foreman skill ephe request
In ephe: bids land on-chain, board state in chat ephe bids

Animated: ephe-request.gif · ephe-bids.gif · ephe-flow.png (plugin run, job 50).

How it is put together

Foreman trust boundary and data flow

One rule decides the whole shape: a claim becomes true only where someone with no reason to believe us can check it. So the contract is the only trust root — escrow custody, the bid book, the one-counter rule, the receipt anchor, the payout and reputation all live there — and every other component is deliberately replaceable. The board, the CLI and the MCP plugin only read. Delete the board and the payer still gets the same guarantee.

Full detail, including the receipt chain and what breaks when each boundary fails: docs/ARCHITECTURE.md. The binding economics are in RULES.md, and every number in this file is backed by an artifact in docs/EVIDENCE_LOG.md.

What each directory is responsible for, and which ones exist on purpose, is tabulated in CONTRIBUTING.md. Measured on the committed tree (46.3 MB across 162 files): everything you need to run Foreman — contracts/, core/, scripts/, web/, plugin-pack/, ops/, the vendored sandbox and the build files — is 0.93 MB across 97 files. The other 45 MB is the evidence, and it divides cleanly: 36.0 MB is the four demo films, 5.8 MB the stills and GIFs that show the same runs inside the documents, 3.35 MB the prebuilt worker WASM a reviewer would otherwise have to compile to reproduce a receipt, and 0.17 MB the 26 markdown files that explain all of it. If the download bothers you, git clone --depth 1 transfers 40.8 MB rather than 65.1 MB: the difference is three earlier cuts of the dual-host film, which was re-rendered to fix an opening-title collision.

Use Foreman in any coding agent

Foreman is not locked to one host. The whole workflow is a single host-agnostic CLI, and it loads as a plugin three ways:

  1. Universal CLI — any agent (or human) that can run a shell drives the full flow: python3 scripts/foreman_flow.py <phase> with phases post · bids · middle · acceptdemo · finish · dashboard · recipe, plus all (the chain end to end), wait (collect a phase run with --bg) and status (the job card).
  2. MCP plugin — plugin-pack/mcp/foreman_mcp.py is a dependency-free Model Context Protocol server: Python stdlib only, JSON-RPC over stdio, four tools (foreman_board, foreman_status, foreman_phase, foreman_wait). This is the normal route; setup: plugin-pack/mcp/README.md and bash plugin-pack/install.sh (below).
  3. Host-native skill pack — optional, per host. plugin-pack/install-ephe.sh is the worked example we ship; the same shape applies to any host that reads its own skill/command format.
Host Status How it connects
OpenCode filmed in this repo (free GLM-5.3-Flash) the mcpServers block in plugin-pack/mcp/README.md
Claude Code filmed in this repo (Qwen 3.8 Flash, qwen3.8-flash-next, served from our own DGX Spark) the same block, in its MCP config
Any other host that speaks MCP same stdio contract, not filmed here register python3 <REPO>/plugin-pack/mcp/foreman_mcp.py
Agents without MCP supported the CLI above, or make cli-board

Two honest notes about that table. Only the two filmed rows are evidence; the third is the same protocol with no host-specific code, which is why we expect it to work, not a claim that we checked it. And foreman_phase/foreman_wait are not read-only: they shell out to scripts/foreman_flow.py under the operator's own testnet credentials, so write phases need keys and the host's tool-approval gate still applies. foreman_board and foreman_status need neither.

Installing the plugin

There is nothing to install. The server resolves the repo root from its own file location, so the checkout you already have is the installation, and one command prints the registration for it:

bash plugin-pack/install.sh           # the mcpServers block, with this checkout's path filled in
bash plugin-pack/install.sh --probe   # plus: start the server and list the four tools it answers

Paste that block into whatever your agent uses to register MCP servers — most read a JSON file, some have a settings screen, and the field is not named the same thing in every host. Look up "MCP server" in your agent's own documentation; the four lines you give it are the same everywhere, and plugin-pack/mcp/README.md holds the shape, the tool contract and a probe to run in a terminal that needs no agent at all.

Read-only tools work immediately, with no key and no account. The write phases (post, finish) run the same CLI a human would, under whoever's testnet credentials are configured, and pass through the host's own approval gate — registering the server grants Foreman nothing.

Hosts that take a native skill pack get one extra convenience on top, and this repo ships the one example it actually uses. ephe is where the films were recorded:

bash plugin-pack/install-ephe.sh     # registers plugin-pack/foreman/ -> ~/.ephe/plugins/foreman
ephe plugin list                     # → foreman on 0.2.0, 3 commands registered

Commands: /foreman-hire, /foreman-board, /foreman-accept. No slash command is required — say "Hire an agent for a market analysis on NEAR and walk the whole escrow flow to the end" and ephe routes the request to the Foreman skill by itself. The skill enforces the dogma: hire → board → exactly one counter-offer → accept only against a fail-closed verified receipt. The demo film shows this exact run, end to end, on testnet. None of this is a dependency: any other host gets the same four tools over MCP, and the ephe pack is only a convenience wrapper around the same CLI.

How the money moves

The binding version of every rule below is RULES.md.

  • post_job locks the budget (0.9 NEAR in the demo) in escrow; 120 s bid window, max 20 bids.
  • place_bid is permissionless — any account may bid inside the window (proven by a contract test and a live guest bid from outside the swarm, job 51). The third-party market offer is shown as a labelled off-chain row, never passed off as an on-chain bid.
  • The foreman account places exactly one counter-offer, priced 10 % under the best bid; the reason is stored on chain (get_counter_reason), and a second counter is rejected (ONLY_ONE_COUNTER).
  • accept before a receipt exists panics NOT_DELIVERED — fail-closed, even for the foreman.
  • The winner executes in Ephemora-Cell; the ES256-signed receipt is anchored via attach_receipt, which checks identity before it reads state.
  • accept pays 90 % of the posted budget to the worker and 10 % to the foreman account — the split is of the budget, not of the winning bid; reputation updates as (old*9 + score)//10. refund_expired returns orphaned escrow permissionlessly.
  • request_cancel + confirm_cancel are a cooperative exit: either party requests, the other confirms, and the full budget returns to the owner (no fault, no reputation change). This closes the delivered-but-stale stalemate; a unilateral ghost still needs arbitration (honest v2 limit).

Tests and gates

Gate Command What it protects
Python suites make test 71 tests — receipts 16, bidding 23, market 12, reputation 11, acceptance 9
Contract suite make contract-test 55 tests — every require! rejection, the bid window, the one-counter rule, fail-closed accept, 90/10 payout, refunds
TypeScript typecheck make typecheck tsc --noEmit over the Intents client and the owner-signing popup — the only gate that reads those files
Lint make lint ruff on syntax errors and undefined names, the findings that can break a money path
Hygiene make hygiene dead links and backticked paths, markdown rows whose cell count differs from their header, leak patterns (reported by length, never content), media budget
Receipt replay make receipt the recorded job-50 receipt re-verifies and re-hashes to the anchored value
Acceptance gate make gate the deliverable against its criteria; judgement-only criteria come back MANUAL

make check runs Python, contract, lint and hygiene — the gates that need nothing but the venv. CI runs those, the typecheck and the two proof replays on every push, so a broken claim fails a build rather than waiting for a reader (.github/workflows/ci.yml).

Known limits

Stated as limits, not as a roadmap:

  • Testnet only, not audited. The deploy script refuses any non-testnet account, and no CI job holds a mainnet key.
  • The swarm is ours. The five bidders are team-controlled sub-accounts. One live guest bid from outside the swarm (job 51) is the honest extent of third-party participation so far.
  • One receipt per job. attach_receipt overwrites, so a re-delivery keeps no history on chain.
  • Reputation is a counter, not a sybil-resistant score.
  • The signature proves which key signed, not who the operator is: the cell key is generated locally into keys/ and is not under any third-party name in v1.
  • Early recorded evidence is partly German. payout_tx_label strings and job 18's counter reason in the sidecar and recipe files were written when the demo was scripted in German, and job 18's reason is what is actually stored on chain — immutable. We kept the records instead of editing them; newer jobs are English, and the hygiene gate keeps German out of the code, scripts and documents, which is the part that ships.
  • A unilateral ghost still needs arbitration. Mutual cancel covers both parties agreeing to stop; it does not decide a one-sided failure.

Questions a reviewer asks

Why does the payout come from the budget and not the winning bid? Because that is what accept computes (fee = budget * 10 / 100, lib.rs). The bid decides who wins; the budget decides what the worker receives. Job 50: best bid 13.56 ¢, budget 900 ¢, payout 810.00 ¢.

What stops you from faking a receipt? Nothing in the receipt alone — it is a signature over an execution report, and the report is only meaningful if the run was really isolated. That is why the sandbox caps fuel, memory and time, logs egress, and why verify_receipt returns False rather than warning. An independent verifier replays the same WASM and inputs and must reproduce the same hash; that replay is a test, not a promise.

Can I trust the board? You do not have to. It is a reader. make cli-board, the MCP tool and the board all call the same view methods on the same contract; when a view is unreachable the board shows a labelled sidecar fallback instead of inventing a row.

Is the 10 % fee real? It is real arithmetic on testnet tokens: the worker gets exactly budget − 10 % and the fee transfer lands on the foreman account minus the accept gas, so the recorded deltas in docs/EVIDENCE_LOG.md read +0.810000 for the worker and +0.089684 … +0.089688 for the fee depending on the run. No mainnet value is claimed anywhere in this repo.

What is actually new? docs/WHY_FOREMAN.md answers that in one page, including what already existed and what we do not claim.

Evidence, docs and licenses

I want to… Go
evaluate the project docs/WHY_FOREMAN.md → docs/EVIDENCE_LOG.md
understand the design docs/ARCHITECTURE.md → docs/SEQUENCE.md → RULES.md
change the code CONTRIBUTING.md (bootstrap, acceptance criteria, PR rules)
report a vulnerability SECURITY.md — private advisory, not an issue
run or redeploy it docs/DEPLOYMENT.md · make help
see what changed CHANGELOG.md
cite it CITATION.cff
find the right document docs/README.md
replay the filmed run artifacts/recipes/recipe_job50.md · one command: make demo-offline

web/board/sidecar/job50.json holds the payout/accept transaction ids behind the board's explorer links.

This repo is Apache-2.0. Declared pre-hackathon baselines (the 19 Oct – 14 Nov 2026 window is what is judged): ephe (BUSL-1.1, demonstrated locally only, not distributed), supernova (Apache-2.0), ephemora-cell (Apache-2.0, vendored wheel as a declared dependency — see vendor/NOTICE), kepta (MIT). Only the NEAR integration inside the window is submitted.

Disclosure: the bidder swarm runs on team-controlled testnet accounts; the board reads the contract live with no backend. Every claim in the demo films maps to a reproducible artifact in docs/EVIDENCE_LOG.md.

About

Foreman hires agent swarms on NEAR: an escrowed job, open bidding, one reasoned counter-offer, and a payout gated on an ES256-signed sandboxed execution receipt that anyone can re-verify. Testnet, MCP-portable.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages