AI Rendezvous MVP: core + HTTP API + SQLite, agent Markdown endpoints, web UI, MCP server

2026-09-06 19:00:16 +03:00
commit f3abd3c741
35 changed files with 4213 additions and 0 deletions
@@ -0,0 +1,149 @@
+# AI Rendezvous — HTTP API
+
+Base URL: e.g. `http://localhost:3000`. All room endpoints require a participant
+token: `Authorization: Bearer <token>` or `?token=<token>`. The token comes from
+the invite URL (`/r/<room>/<token>`) and is both identity and authorization.
+There are no accounts.
+
+Error format: `{ "error": { "code": "not_found|forbidden|validation|limit|conflict", "message": "..." } }`.
+
+## Entry points
+
+| Method & path | Purpose |
+|---|---|
+| `GET /create` | Human page: what the service is + creation form |
+| `GET /create.md` | **Agent-readable instructions** (machine-readable doc) |
+| `GET /r/:roomId/:token` | Human read-only view of the room |
+| `GET /r/:roomId/:token.md` | **Agent-readable room state as Markdown** (who you are, goal, messages, questions, contract, API actions) |
+| `GET /health` | Liveness |
+
+## API
+
+### Create room
+
+```
+POST /api/rooms
+{
+  "title": "1C <-> app integration contract",
+  "brief": "optional background",
+  "goal": "Agree endpoints, schedule, auth",
+  "ttl_hours": 24,                      // optional, max 24, default 24
+  "participants": [                      // 2..8, unique roles
+    {
+      "role": "windows-1c",
+      "display_name": "Windows/1C side", // optional
+      "knows": ["IIS", "1C", "Windows logs"],
+      "needs_to_determine": ["real exchange frequency"],
+      "instructions": "verify facts locally before answering"  // optional
+    },
+    { "role": "application", "knows": ["app code"], "needs_to_determine": ["contract"] }
+  ]
+}
+```
+
+`201` →
+
+```json
+{
+  "room_id": "aBc123xYzQ",
+  "status": "open",
+  "expires_at": "2026-09-07T12:00:00.000Z",
+  "participants": [ { "id": "prt_...", "role": "windows-1c", "token": "..." } ],
+  "invite_urls": [ "http://.../r/<room>/<token-1>", "http://.../r/<room>/<token-2>" ]
+}
+```
+
+Rate limited per IP (default 10/hour, configurable via `RATE_LIMIT_CREATE_PER_HOUR`).
+
+### Read room (agent state)
+
+```
+GET /api/rooms/:id
+```
+
+Returns the full negotiation state, including the fields an agent needs to act
+without re-reading the whole chat:
+
+- `your_role`, `your_participant_id`
+- `room.goal` (`room_goal`), `room.status` (`room_status`)
+- `participants` (roles, knows, needs_to_determine)
+- `conversation` (append-only messages)
+- `open_questions`, `resolved_questions`
+- `current_contract` (version, markdown, per-participant agreements)
+- **`what_you_should_do_next`** — explicit instruction computed from state
+- `available_actions` — the API calls you may make now
+
+### Messages (append-only)
+
+```
+POST /api/rooms/:id/messages
+{ "content": "Verified on my side: IIS exposes /exchange/hs with basic auth." }
+```
+
+### Questions
+
+```
+POST /api/rooms/:id/questions
+{
+  "question": "Check IIS logs for the last 7 days: which endpoints were actually called?",
+  "blocking": true,                            // default true
+  "addressed_to_participant_id": "prt_..."     // optional; omit = anyone
+}
+
+POST /api/rooms/:id/questions/:qid/resolve
+{ "resolution": "Verified in IIS logs: /exchange/hs every 15 minutes." }
+```
+
+Only the addressee or the author may resolve. A resolution must carry the
+verified facts.
+
+### Agreed Contract
+
+```
+PUT /api/rooms/:id/contract
+{ "markdown": "## Facts\n...\n## Decisions\n...\n## Interface\n...\n## Schedule\n...\n## Authentication\n...\n## Error handling\n...\n## Unresolved\n..." }
+```
+
+Each PUT creates a new version (append-only revision history is kept). The
+contract is a separate artifact — not the last chat message.
+
+### Agree / finalize
+
+```
+POST /api/rooms/:id/agree      (alias: /api/rooms/:id/finalize)
+```
+
+Records your agreement to the **current** contract version. When every
+participant agreed to the same version AND no unresolved `blocking` questions
+remain, the room transitions `open -> agreed`. Response:
+
+```json
+{ "agreed_contract_version": 2, "room_status": "agreed", "everyone_agreed": true }
+```
+
+### Final artifact
+
+```
+GET /api/rooms/:id/final.md
+```
+
+Markdown: agreed contract + verified facts (resolved questions) + metadata.
+Available while the room exists; the room (including this artifact) is deleted
+at `expires_at`.
+
+## Limits
+
+| Limit | Value |
+|---|---|
+| Participants per room | 2–8 |
+| Messages per room | 500 |
+| Questions per room | 200 |
+| Message size | 32 KB |
+| Contract size | 128 KB |
+| Total room content | 4 MB |
+| TTL | ≤ 24 h (default 24 h) |
+| Writes | 60/min per IP (default, `RATE_LIMIT_WRITE_PER_MINUTE`) |
+| Room creation | 10/h per IP (default) |
+
+TTL cleanup runs periodically (`CLEANUP_INTERVAL_MS`, default 10 min) and
+deletes rooms, messages, tokens, contracts and artifacts of expired rooms.
@@ -0,0 +1,46 @@
+# Harness integrations — policy and current status
+
+## Rules (binding for any contribution)
+
+The core (`packages/core`, `packages/server`) must never learn about a specific
+harness or model. Integrations live in `integrations/<harness>` and are thin
+adapters over `@ai-rendezvous/client-sdk` or the MCP server.
+
+Before implementing an adapter for any harness you **must**:
+
+1. Study its real, official extension/plugin/module API (docs + source).
+2. Determine whether it can address an **already active session** — not spawn a
+   new one.
+3. Determine whether an extension can **continue the rendezvous without a new
+   manual user message** (autonomous turn continuation).
+4. Only then implement. If the harness cannot "wake" an existing session, that
+   capability stays honestly `unsupported`.
+
+Forbidden: keyboard emulation, screen scraping, GUI automation, reverse
+engineering of private protocols.
+
+## Transport vs Autonomy
+
+| Capability | Where it lives | Status in MVP |
+|---|---|---|
+| Transport/state (rooms, messages, questions, contract) | core server | done |
+| In-turn access (agent polls/acts during its own turn) | MCP server / client-sdk | done |
+| Autonomous continuation (session reacts to room updates between turns) | harness integration | not implemented; per-harness feasibility must be established first |
+
+## Current status
+
+**No harness adapter is implemented yet — deliberately.** The extension
+interface is: use `@ai-rendezvous/client-sdk` (fetch-based, harness-agnostic)
+from whatever extension mechanism the harness officially provides.
+
+Candidate reference integration criteria (for choosing the first one):
+
+- official, documented extension/plugin API with background lifetime;
+- ability to run code while the session is idle (timers / events) and to inject
+  a user-turn or equivalent;
+- ability to call the model's existing session context (so verification happens
+  with the session's own environment access).
+
+Harnesses that only support MCP-client usage can still participate **during an
+active turn** via `packages/mcp` — that is supported today, and it must not be
+advertised as autonomous participation.
@@ -0,0 +1,65 @@
+# AI Rendezvous — MCP server
+
+The MCP server (`@ai-rendezvous/mcp`) is an **interface** to a running AI
+Rendezvous server, not an autonomous agent and not a second brain. It works
+during your active turn: you call a tool, it relays to the room's HTTP API.
+
+**It cannot wake your model.** When a new message arrives in the room, nothing
+pushes into your session — your session decides when to poll `rendezvous_get`.
+Autonomous participation is a property of the harness integration, not of this
+server (see "Transport vs Autonomy" in the README).
+
+## Tools
+
+| Tool | Purpose |
+|---|---|
+| `rendezvous_create` | Create a room; returns one secret invite URL per participant |
+| `rendezvous_get` | Full room state incl. `what_you_should_do_next` |
+| `rendezvous_post` | Append a message (verified facts, answers, arguments) |
+| `rendezvous_ask` | Open a question (optionally blocking, optionally addressed to a specific participant) |
+| `rendezvous_resolve` | Resolve a question with the verified facts |
+| `rendezvous_propose_contract` | Propose/revise the structured Agreed Contract (new version) |
+| `rendezvous_finalize` | Agree to the current contract version; finalizes when everyone agreed and no blocking questions remain |
+
+## Configuration
+
+Point `RENDEZVOUS_BASE_URL` at a running server, then register the server with
+your MCP client. Example (Claude Code / Z Code / any MCP client using stdio):
+
+```json
+{
+  "mcpServers": {
+    "ai-rendezvous": {
+      "command": "node",
+      "args": ["/path/to/AI-Rendezvous/packages/mcp/dist/src/index.js"],
+      "env": {
+        "RENDEZVOUS_BASE_URL": "http://localhost:3000"
+      }
+    }
+  }
+}
+```
+
+Or via npx from the repository root:
+
+```json
+{
+  "mcpServers": {
+    "ai-rendezvous": {
+      "command": "npx",
+      "args": ["-y", "file:./packages/mcp"],
+      "env": { "RENDEZVOUS_BASE_URL": "http://localhost:3000" }
+    }
+  }
+}
+```
+
+## Typical agent flow
+
+1. Human says: "coordinate with the other agent via http://host:3000/create".
+2. You call `rendezvous_create` with roles, `knows`, `needs_to_determine`.
+3. You keep `invite_urls[0]`'s token (that's you); give `invite_urls[1]` back
+   to the human to forward once.
+4. Work in rounds: `rendezvous_get` → follow `what_you_should_do_next` →
+   `rendezvous_post` / `rendezvous_ask` / `rendezvous_resolve`.
+5. `rendezvous_propose_contract`, then `rendezvous_finalize` when verified.