Human-guided multi-model annealing. Built by agents that have to share the work.
Damascus routes an idea, decision, or software artifact through independent expansion, adversarial review, concrete checks, reconstruction, and human acceptance. It keeps the evidence, disagreements, rejected criticisms, and reasons for changes. Models are replaceable instruments; the schedule and ledger are the product.
The same agents will build the service in Hyperia. The damascus-work MCP server connects them to a central Work Broker that assigns bounded tasks, requires handoffs, prevents session aliases from resetting quotas, and separates implementation, independent review, and human acceptance.
Human holds the tongs. 🔧
v0.2: build plan + coordination-only reference implementation.
Included: a transactional broker, private loopback API, eight-tool stdio MCP wrapper, family-based quotas, checkpoints, task inboxes, immutable text artifacts, review and human gates, and a local test suite.
Not yet included: Hyperia notification integration, isolated agent launcher, workspace/process enforcement, trusted test execution, Git merge automation, customer annealing API, or live provider adapters. The MCP wrapper needs the external SDK and a real client interoperability check. See implementation status.
The broker enforces its own API. An agent with an unrestricted host shell can bypass a coordination server. Hard work-sharing enforcement requires the planned launcher/executor/network boundary and its integration tests. The server reports coordination_only until that exists; there is no flag here that pretends to turn containment on.
Human objective
→ independent Gemini / Grok branches
→ Claude / GPT challenges
→ assumptions, counterexamples, tests and source checks
→ reconstruction from accepted changes
→ GPT final model gate
→ human acceptance, or reheat
The human selects branches and accepts or rejects criticisms throughout the run. Model disagreement creates a question to investigate. Unsupported claims can remain as explicitly labeled hypotheses. A source or test establishes more than another model's agreement.
The provider roster from the original plan remains: xAI, Anthropic, Google, OpenAI, DeepSeek, and Z.AI. Model IDs are configuration, not hardcoded assertions about availability. Reasoning-capable modes can be used across families.
Hyperia agent pane
→ damascus-work MCP
→ Work Broker
→ bounded implementation or review lease
→ checkpoint / candidate / handoff
→ different-family review
→ human acceptance
Every agent should contribute real implementation and testing, not leave one model to write everything while the rest comment. The scheduler prefers the less-used implementation/review role for each family when eligible work exists. Task scopes stay small enough to hand over.
| Control | Default behavior |
|---|---|
| Identity | Operator-enrolled principal, fixed model family |
| Active work | One active lease per family, across all sessions |
| Slice | 15 minutes and 30 ordinary mutating broker operations |
| Rotation | Family cannot lead the least-served enabled family or take consecutive allocations |
| Handoff | Saved progress and next step; unfinished work goes to another family |
| Reopening a session | Same family, same counters; no fresh quota |
| Review | Non-contributing family, exact artifact hash |
| Acceptance | Human-only; review does not merge code |
| Communication | Bounded task-scoped inbox, no arbitrary pane addressing |
| Missing peer | Wait visibly; human changes availability explicitly |
These numbers are initial settings, not measured optimums. Allotted slices are observable; actual intellectual effort is not. A lease budget cannot measure provider tokens hidden inside a separate CLI. See broker contract.
Python 3.12+. The broker and tests use only the standard library. Run from this repository's root.
PowerShell:
$env:PYTHONPATH = "$PWD/src"
python -m unittest discover -s tests -v
python -m damascus_work init --state .damascus-state --tasks config/tasks.json
python -m damascus_work serve --state .damascus-state --port 9790Bash:
export PYTHONPATH="$PWD/src"
python -m unittest discover -s tests -v
python -m damascus_work init --state .damascus-state --tasks config/tasks.json
python -m damascus_work serve --state .damascus-state --port 9790init refuses to overwrite existing state. It writes operator and agent credentials under .damascus-state/credentials/; the database stores hashes. Keep that entire directory operator-only. Never mount it into an agent runtime or commit it. POSIX file modes are set; Windows ACLs still require operator configuration.
From another human-controlled terminal:
python -m damascus_work admin --state .damascus-state status
Use the operator-only inspect action with a task ID to view candidate bytes, hashes, review findings and messages before accepting.
The sample project contains four bootstrap review tasks. After review and installation of the trusted enforcement components, initialize a separate build project with config/service_tasks.json to construct the service under the approved governor. Do not modify live state files to change a project's queue.
Install the wrapper dependency in your chosen virtual environment:
python -m pip install -e ".[mcp]"
This intentionally selects the official SDK's v1 maintenance line (mcp>=1.28,<2). Upgrading to v2 is a separate compatibility task. The initial environment could not install this dependency, so the wrapper has not completed an actual MCP handshake here.
Configure a stdio server named damascus-work with:
command: <absolute path to the virtual environment's Python>
args: -m damascus_work.mcp_bridge
The trusted launcher supplies DAMASCUS_BROKER_URL and exactly one DAMASCUS_AGENT_TOKEN to that process. No token goes in a committed config. See config/mcp.stdio.example.json; client-specific registration belongs in the verified local launcher.
The wrapper connects to the private broker API. It does not give the agent database access or a Hyperia identity. Keep the loopback API private. Container/remote deployment requires the separate authenticated network boundary described in the integration plan.
| Tool | What it does |
|---|---|
work_status |
Inspect assignment, quota and enforcement mode |
work_next |
Ask the server for one eligible slice |
work_checkpoint |
Save summary, next step and optional artifact text |
work_handoff |
Release work or report a blocker |
work_submit |
Store a candidate and queue independent review |
work_review |
Review the exact assigned candidate |
work_message |
Leave a bounded note/question/blocker for the task |
work_inbox |
Read messages for assigned tasks |
WAIT_FOR_PEER means stop taking new work. BUDGET_EXHAUSTED permits one bounded closeout handoff before lease expiry. LEASE_EXPIRED denies further mutation; the existing checkpoint remains. Status and inbox stay available while waiting. A response to an idempotent retry is a historical receipt, not permission to use an expired lease.
No agent MCP tool can create approved tasks, enroll identities, change the roster, reset quotas, alter policy, accept its own artifact, or merge. Stored artifacts are text only and are never executed by this seed.
Hyperia remains the human-visible workspace. The enforced launcher will remove agents' direct Hyperia credentials/configuration and block direct sidecar network access, including anonymous reads and token issuance. The trusted bridge alone sends safe wake notices. Task data moves through the broker inbox; one agent never gets raw keystroke access to another's pane.
Removing HYPERIA_AGENT_TOKEN alone is insufficient. Shared filesystem writes, global MCP configuration, raw HTTP/WebSockets, shell access, settings, notes, and token minting must be tested as bypass paths. Details and the fail-closed rollout gate are in Hyperia integration.
- Independently review the bootstrap and install its trusted control boundary.
- Make forced sharing pass real Hyperia/runtime bypass tests.
- Build one complete mock annealing run using bounded, cross-reviewed agent contributions.
- Add live adapters, durable service workflows, human UI, tenant/key isolation, and measured evaluations.
No multi-tenant service or demonstrated annealing benefit is claimed by this repository seed. The original plan is preserved, and every design change is called out in the updated build plan.
Read AGENTS.md before taking work. The human approves task boundaries and acceptance criteria. A reviewer supplies findings and evidence; a critic does not acquire automatic authority over the objective. Security-critical changes to the governor remain inert artifacts until independently reviewed and installed by the human.
Source basis and inspected external documentation: SOURCES.md. Licensing for the new repository remains the owner's decision; no license has been silently selected.