Skip to content

INDEX.md

Latest commit

 

History

History
70 lines (51 loc) · 3.71 KB

INDEX.md

File metadata and controls

70 lines (51 loc) · 3.71 KB

Agent Loop

The agent loop is the first-class product surface of Markup. A user creates an annotation; an automation client reads the annotation, applies a fix, and replies. The endpoints under this folder are the contract that consumers depend on — AI dev assistants (Claude Code, Cursor, Aider), agent frameworks (LangGraph, CrewAI, AutoGen), and in-house orchestrators alike.

Silent drift in any of these endpoints breaks consumers. See the agent-loop rule for the strict-update policy.

Read first

  • Overview — the cycle end-to-end with byte costs
  • Endpoints — /context, /version-patch, /region, /diff, /tldraw
  • Uploads — POST /api/mockups, POST /api/mockups/[id]/version (raw HTML + zip, size cap)
  • Patch format — unified-diff conventions for /version-patch

At a glance

A complete cycle from user comment to agent reply:

USER (browser)                    AGENT (Bearer or cookie)
─────────────                     ──────────────────
+ Comment                         │
draw + textarea + save            │
   POST /annotations              │
   creates Annotation +           │
   Thread + Message + tldraw.json │
   (base64 stripped)              │
                                  GET /api/agent/context/[aid]
                                   ↓ aggregator (item C)
                                   ├─ annotation
                                   ├─ thread (msgs + status)
                                   └─ current_version
                                       ├─ files: { "index.html": <inline> }
                                       └─ diff_since_creation (unified)
                                  
                                  PATCH /api/mockups/[id]/version-patch
                                   body: { base_version_id, patches: { file: <unified diff> } }
                                   server validates → creates new version
                                  
                                  POST /api/threads/[tid]/reply

Token budget per cycle

Step Bytes Notes
GET /context ~3–10 KB JSON Single read; ETag-cacheable for the no-change case
PATCH /version-patch ~0.5–5 KB body Unified diff; binary files reused from base by reference
POST /reply ~0.5–2 KB body Plain text
Total ~5–15 KB per round-trip Replaces the legacy 6+ round-trip flow that ran ~660 KB upstream

These numbers come from the v1.3 spec and are baseline expectations — keep them honest as the schema grows. If a change pushes a single endpoint past its category, restate the budget in this doc.

Surface ownership

The agent-loop endpoints are not generic CRUD. They have non-trivial semantics that other parts of the codebase don't need to know about:

  • Unified-diff apply / render → see src/lib/diff/apply-unified.ts and render-unified.ts
  • ETag composition for /context → see Endpoints

When a change touches any of those, the matching doc here is the contract — update it first.

Out of scope

The following items are designed but not shipped — they live in docs/future-features.md:

ID Item Why parked
#20 LLM-derived intent classification Adds vendor SDK + per-call cost; deferred until a downstream consumer needs it
#21 Agent sub-role header (X-Agent-Subrole) Cheap (~0.5d), park until 3+ personas are deployed
#22 Multi-agent routing / inbox Depends on #20 + #21; co-spec with the multi-agent role taxonomy in #7