Eve library

Remote coding agents and the Eve task board

Other

Revision 4

On this page

Endpoint: https://api.dev.oshunsynthetics.com/v1/eve-board. This dedicated worker service operates the single shared Eve board. It is separate from the BFF's read-only tools. UAT reads the same board, but does not expose a second worker API or maintain a second set of claims.

Worker setup#

Pull current origin/main and use Node 22.13 or newer. Remote mode needs no PostgreSQL driver, database password, open database port, or SSH tunnel. Document search, section reads, revision history, and task briefs use the authenticated APIs. Keep the checkout for implementation and Git verification. Tracker checkboxes and line numbers are historical provenance; do not edit them or import their old state back into Eve. An operator issues a separate credential for each worker identity. Transfer that JSON file through your existing secure administrative channel:

sh
mkdir -p ~/.config/oshun
chmod 700 ~/.config/oshun
install -m 600 /secure/path/worker.json ~/.config/oshun/eve-api.json
./eve remote whoami
./eve next
./eve show <task-key>
./eve context <task-key>
./eve claim <task-key>
./eve start <task-key> --token <printed-token>
./eve renew <task-key> --token <printed-token>
./eve note <task-key> --token <printed-token> --text 'Verification progress...'

The credential supplies the identity. --agent and EVE_AGENT, if supplied, must match it. Use a different identity for each independently working agent. Set EVE_API_CONFIG=/absolute/private/file.json for another credential location, or inject both EVE_API_URL and EVE_API_KEY through the worker's secret environment. Never put keys in Git, command arguments, evidence, prompts, or URLs. API mode refuses a failed connection instead of falling back to direct database access or creating a separate local board.

Complete and park work#

Run all applicable verification, then:

sh
./eve done <task-key> --token <printed-token> \
  --evidence 'Files changed; verification commands and counts; results.'
# Commit and push the implementation to origin/main; do not change the tracker.

done records HEAD as the implementation commit unless --commit <full-sha> is supplied. This reference does not assert that tests passed or that the commit was pushed; those remain worker requirements. Stored family policies still apply to task transitions. Historical source anchors do not gate database-owned completion or require a tracker rewrite.

sh
./eve park <task-key> --token <printed-token> --reason human \
  --note 'The owner must provide the required account access.'
./eve unpark <task-key>
./eve release <task-key> --token <printed-token>

API parking requires a current claim and token. Notes on a claimed task require its owner's current token. Default worker credentials grant task reads and work; authoring and independent review require explicit operator grants. Credentials cannot import trackers, rewrite the registry, bypass claims, or administer keys. Reads include next, show, search, list, families, history, stats, context, prompt, and document reads. check and drift use a read-only in-memory snapshot obtained over HTTPS. Historical source drift does not block database-owned completion. Do not regenerate trackers or import their old state back into Eve.

Documents and task briefs#

Document reads use https://api.dev.oshunsynthetics.com/v1/eve-content and require content:read in addition to task scope board:read. An operator can issue a worker key with --scopes board:read,board:work,content:read. Existing board-only keys retain their original permissions. The APIs return an error if access is denied or the service is unavailable; the CLI does not substitute local Markdown or omit a task's source rules silently.

sh
./eve docs search 'architecture' --kind architecture --limit 20
./eve docs unclassified --page 1 --limit 20
./eve docs show docs/path/to/design.md --json
./eve docs show docs/path/to/design.md --section section:2 --revision 3
./eve docs show docs/path/to/design.md --text --revision 3 --offset 0 --length 16000
./eve docs history docs/path/to/design.md --limit 20
./eve docs related <task-key>
./eve context <task-key> --max-chars 20000 --json
./eve prompt <task-key> --max-chars 12000

Use a document UUID or its preserved legacy path. docs show returns a paginated outline by default; a section ID, heading, or legacy #anchor selects text. Presentation slide IDs remain usable as anchors. Follow the returned nextOffset and pin --revision when continuing a long document, so an intervening edit cannot mix versions. Text pages have a 65,536-character ceiling and preserve Unicode character boundaries. Task briefs include stored family policies, source rules for the task's section, dependencies, and related documents. They report omitted sections and the source revision for follow-up reads. API-native tasks use their stored body without requiring a source file.

The MCP tools expose the same reads: eve_document_query actions outline, text, and context, and eve_task_query command context. All use the configured credential and API destination.

The repository's .mcp.json registers oshun-eve using node tools/workbench-mcp/eve-server.mjs. Pull main and reload your client's project MCP configuration (or start a new session). It uses the same private ~/.config/oshun/eve-api.json or inherited EVE_API_CONFIG as the CLI; no key is stored in the registration. The adapter currently offers 18 tools, including task definitions, document relationships/successors, and publication reads, freezes and promotions. Tool availability does not grant permission: the API checks the configured key's scopes on every call. Existing clients may require their normal project-server trust prompt before exposing native tools.

Database-owned task definitions#

The task cutover is active. Read GET /capabilities or POST /read with {"command":"capabilities"} to confirm taskAuthority: "database". done, park, and unpark update PostgreSQL and its journal directly; omit original and do not edit a tracker. The CLI checks capabilities itself.

An operator can issue an author key with --scopes board:read,board:work,board:author. Only a separately authorized reviewer should receive board:review; review identity must differ from the task's shipper. Examples after cutover:

sh
./eve add --family eve --id EXAMPLE.1 --title 'Add a reviewed capability' \
  --body 'Acceptance criteria and implementation context.'
./eve show eve:EXAMPLE.1 --json
./eve edit eve:EXAMPLE.1 --expected-version 1 --body 'Revised acceptance criteria.'
./eve dep add eve:EXAMPLE.1 eve:EXAMPLE.2 --expected-version 2
./eve history eve:EXAMPLE.1 --limit 20 --json
./eve verify eve:EXAMPLE.1 --expected-version 5 \
  --evidence 'Independent verification commands and their passing results.'

New tasks default to later so authoring does not silently expand the ready queue. Edits, dependency changes, rejection, and verification require the expectedVersion returned by a fresh read. Changes to a leased task also need its owner's fencing token. Stored family policies still apply. Finished task definitions are immutable; create a follow-up task for new work. Original source hashes remain provenance, and the journal preserves earlier definitions.

The MCP adapter exposes eve_task_query with capabilities and paginated history, eve_task_transition for completion/parking, and eve_task_definition for creation, edits, dependencies, rejection, and review. It uses the same HTTPS API, credential scopes, version checks, and UUID retry IDs as the CLI. Tool arguments cannot override worker identity or destination.

Interrupted requests#

Every mutation uses a UUID request ID and a PostgreSQL replay record. The CLI saves its input under .cache/eve-task-board/remote-requests/ before sending it. Repeating the same command recovers its result instead of applying it twice.

Historical requests created before cutover may still have prepared tracker edits. Those edits used two steps: the API prepares an edit without changing the board; the CLI applies it locally and confirms its hash; the API rechecks the lease and tracker state, then commits the update and replay receipt together. Expired leases, changed policy, or another edit to that tracker cause a refusal. Database-owned task writes do not prepare or apply tracker edits. Resolve an old pending request explicitly; never manually apply its stale tracker patch.

sh
./eve remote pending
./eve remote resume <request-id>
./eve remote abort <request-id>

resume also recovers a successful commit whose reply was lost. abort cancels an uncommitted operation and restores the original tracker only if it still exactly matches the prepared edit. It refuses to undo a completed operation or overwrite subsequent local changes. Prepared edits expire after 15 minutes; replay records remain for 30 days. Resolve pending operations within that period. Keep the pending files through network outages. A replacement key for the same identity can recover requests after a credential expires or is revoked.

Operator key administration#

From a current checkout on Hetzner, using authorized operator credentials:

sh
node tools/eve-task-board/api-keys.mjs issue \
  --agent build-server-02 \
  --out /root/.config/oshun/workers/build-server-02.json
node tools/eve-task-board/api-keys.mjs list
node tools/eve-task-board/api-keys.mjs set-scopes <key-id> \
  --agent build-server-02 \
  --scopes board:read,board:work,board:author,content:read,content:write
node tools/eve-task-board/api-keys.mjs revoke <key-id>

Issuance writes a new 0600 file, refuses overwrites, and prints only its path and non-secret metadata. PostgreSQL stores a SHA-256 digest of the 256-bit random secret. Keys expire after 90 days by default; --days 1 through --days 365 are supported. --read-only grants board reads without mutations. To rotate, issue a replacement for the same agent to a new file, install it on the worker, then revoke the old ID. Revocation and expiry are enforced on every request, including committing a previously prepared tracker edit.

set-scopes replaces the complete permission list on an existing active key; include every scope it should retain. It requires the key's current agent name, prints previous/new scopes without the secret, and preserves the key ID, secret, identity, and expiration. Grants and removals take effect on the next request; the worker does not need a new file or a restart. Other keys for the same agent are unchanged. Expired or revoked keys cannot be reactivated this way. This is an operator command, never an HTTP or MCP key-administration endpoint.

A separate reviewer agent is optional. A human operator can review in Eve and explicitly promote a tested publication to UAT. If a reviewer agent is used, give it its own identity and only the required board:review or content:review scopes; the reviewer must differ from the task's shipper or document's editor. content:publish is a separate publication permission. Ordinary worker authoring does not grant any of these permissions. CI prepares and tests Dev publications; UAT promotion remains an explicit operator action.

HTTP protocol#

All data endpoints require Authorization: Bearer <worker-key>. POSTs require Content-Type: application/json. Do not follow redirects with credentials. Browser Origin headers are rejected; this service is for machine clients.

Method Path below /v1/eve-board Input/result
GET /whoami Agent, key ID, scopes, expiration
GET /capabilities Protocol, task authority, supported actions
POST /read command: next, show, context, search, list, families, stats, history, capabilities
POST /actions Action arguments; UUID v4 Idempotency-Key header
GET /requests/<id> This worker's request state and result
POST /requests/<id>/commit {"fileHash":"<prepared afterHash>"}
POST /requests/<id>/abort {}; refuses completed requests
GET /snapshot/board Board data for local verification
GET /snapshot/documents Legacy document catalog for verification
GET /healthz Public protocol/revision; no board data

A task a worker files with ./eve add starts later unless it passes --status ready; ./eve edit <key> --status ready --expected-version <v> promotes it afterwards. Placement (--after) exists only in SQLite mode; the API appends the item to its section.

Read examples: {"command":"next","family":null,"limit":1}, {"command":"show","key":"family:ID"}, or {"command":"search","query":"postgres","limit":10}. A claim body is {"action":"claim","key":"family:ID","ttl":"4h"}. Its response has id, state: "completed", and result containing the key, authenticated agent, fencing token, and expiration. Actions are claim, start, renew, release, note, done, park, and unpark. Subsequent leased actions include token. note takes text; done takes evidence and optional full commit; park takes reason and note.

Database definition actions are create-task, edit-task, set-dependency, reject-task, and verify-task. Creation takes family, key, title, and optional body, section, status, and a dependsOn array. Other definition actions take key and expectedVersion. Edits take title, body, or status; dependencies take operation (add/remove) and one dependsOn key; rejection takes reason; verification takes evidence. History reads take key, limit, and optional cursor; pass the returned nextCursor for the next page. Mutations retain UUID idempotency protection.

Before the database cutover, tracker actions also took original, the checkout's UTF-8 tracker content. Their initial response had state: "prepared", expiresAt, and a patch with path, beforeHash, afterHash, and after. These fields remain relevant only to recovery of historical requests. After cutover, the API refuses to commit a previously prepared tracker edit. Use the CLI's pending-request recovery commands; current task actions write directly to PostgreSQL.

Statuses: 401 invalid/expired/revoked key; 403 scope/identity refusal; 409 lease/anchor/replay conflict; 413 oversized input; 429 quota; 503 temporary unavailability. Retry uncertain mutations with the same ID and identical input. Limits: 120 requests/minute/key, a rolling 24-hour mutation allowance per worker identity (the API's default is 1000; the Dev host is provisioned with 10000 — see Deployment), 100 list results, 4 MiB per tracker, and 96 MiB per full verification snapshot. Reads never count against the allowance; the refusal is 429 daily_request_limit and names the cap. No SQL or shell commands are accepted. Task scopes are board:read, board:work, board:author, and board:review. Content scopes are managed separately. Adding author or reviewer support does not expand any existing key's permissions.

Deployment and backups#

The native eve-worker-api.service listens on loopback port 18883, behind Caddy's dedicated path on api.dev.oshunsynthetics.com. Its eve-api OS user cannot write the release checkout. Its separate PostgreSQL role can read the board/catalog and update tasks, claims, journals, and request receipts. It cannot create keys, import catalogs, or change schemas. PostgreSQL remains private; the BFF keeps its read-only role. The API starts on boot, restarts on failure, and waits for the mounted volume.

The daily mutation allowance is EVE_API_DAILY_MUTATIONS in the unit, written by provision-api.py --daily-mutations (default 10000; the code's default when the variable is unset is 1000). To change it on the host without a release, write EVE_API_DAILY_MUTATIONS=<n> to /etc/oshun/eve-worker-api.env (mode 0600, root) and systemctl restart eve-worker-api.service; the unit reads that file after its own Environment= lines, so the file wins and survives re-provisioning. A value that is not a positive whole number stops the service at boot.

Dev CI runs the Eve suite against disposable PostgreSQL when its implementation changes, then installs it from the verified release. UAT promotion does not replace this shared worker service. Existing pgBackRest physical/WAL backups include the eve_api schema's key digests and replay records. Plaintext keys stay with operators; issue replacements if lost. A daily timer removes replay rows older than 30 days without pruning task journals.

sh
systemctl status eve-worker-api.service eve-worker-api-prune.timer
journalctl -u eve-worker-api.service
python3 infra/hetzner/eve/verify-api.py --source "$PWD" \
  --node /root/.nvm/versions/node/v24.14.1/bin/node
# After a fresh backup includes at least one issued key:
python3 infra/hetzner/eve/restore-drill.py --require-api

Logs contain operation, agent, key ID, and status, with no credential, tracker body, or evidence. Mutations retain the board's existing journal under the authenticated worker identity. This remains one host: workers retry after an outage and keep their pending request records.

Media and document attachments#

The same credential accesses the media API and MCP query tool. Originals stay in private object storage, with immutable aliases and recovery copies; agents do not need bucket or database credentials.