OpenEik 0.2 specification

Part VII. Agent interface

An agent works on an OpenEik model as it works on a code base: it looks at the map, opens the few files that matter, asks questions instead of reading everything, changes a few records through checked commands, and looks at what it did. This part fixes the contract an agent host offers so that any agent, through any protocol, can do that. The Model Context Protocol (MCP) is the protocol the reference implementation uses; nothing here depends on it.

1. The operations

An agent host MUST offer these operations, under any names, and MUST describe each one's arguments to the agent in a machine-readable form:

and SHOULD offer:

Reference: the request actions of automationRequest in src/automation.ts (summary, tree, read, query, execute, execute_batch, guide, snapshot_2d, snapshot_3d, changes, report_problem and others); the reference tool catalogue (src/core/automation/automationCatalog.ts, 53 tools) serves them over MCP, and the headless server adds eik_validate and eik_export_ifc (server/eikMcpServer.ts).

2. Map first, then drill down

1. tree with a path answers one folder of the layout (Part III): its sub-folders with a count and a one-line summary each, or its records as rows. Names MAY stand for ids in the path (a level's name for its id).
2. Each tree answer MUST name its parent and SHOULD say what to call next.
3. summary SHOULD stay small whatever the model's size: it counts, it does not list every record.

From the reference host on examples/one-storey-house, tree {path: "architecture/level-0"} answers four folders: door (1 record, "types: Door 1000 x 2100 1"), slab (1), wall (5, "types: Exterior wall 300 4, Partition 100 1") and window (2), with its parent architecture.

Reference: treeMap in src/core/versions/navigate.ts; summaryOf.

3. Read in tiers

1. read MUST offer at least two tiers:
   • index: one row per element, as columns and rows (the reference columns are id, category, typeId, name, levelId, hostId, revision, bounds, with bounds as [xmin, ymin, zmin, xmax, ymax, zmax] in mm);
   • full: the records themselves. A host MAY add derived values beside a record (its quantities, its joined ends, its faces), and MUST keep them apart from the record's own members so that an agent never writes them back.
2. Reads MUST be paged: offset and limit (at most 500, default 50), and optionally a byte budget.
3. Every list answer MUST carry the honesty fields: total (how many match), returned, offset, nextOffset (or null), truncated (whether anything matching was left out), and the host's sequence.

Reference: the read action in src/automation.ts; indexColumns in src/core/model/modelSummary.ts; readBudgetSchema in src/core/model/modelFilterSchema.ts.

4. One filter for reading and for looking

Reads, queries and snapshots MUST accept one filter, whose criteria combine with AND:

Reference: modelFilterSchema in src/core/model/modelFilterSchema.ts; applyModelFilter.

5. Budgets: cap what arrives unasked, never what can be asked for

1. A host SHOULD hold every answer it sends into an agent's conversation under a budget (the reference uses 20 000 tokens, counted as 2.5 characters per token). An answer over the budget MUST NOT be cut off silently: the host answers with what the answer would have held and how to ask for less.
2. A host MUST let an agent ask for a whole answer deliberately (whole: true), and MUST offer the whole model, as the folder or the single-file form, for agents that work on files with code.

Reference: ANSWER_TOKENS, CHARS_PER_TOKEN and the held answers in src/core/automation/answerBudget.ts.

6. The write loop

1. An agent writes through commands (Part V): a dry run first, then the real run, both with preconditions.
2. Every accepted write answers with affected and verify (Part V, section 9), so that the agent can look at exactly what changed.
3. A host that keeps a model in a folder MUST write every accepted change to the folder before it answers, and only the records that changed.
4. A host MUST let an agent edit record files directly and MUST see those edits: the next request reads them and checks the whole model; a folder that no longer checks is reported, naming the file and the rule, and the last good model is kept.
5. validate checks the folder as it is now and says either that it is valid or what is wrong. "Done" for an agent means validate reports no errors.

Reference: EikSession in server/eikSession.ts (request, validate, sync, save); eik_validate in server/eikMcpServer.ts.

7. The guide

Knowledge an agent needs is served on demand, not all at once.

1. A host MUST serve a guide core, read once at the start: the conventions of Parts I and II, the tiers, the filter, the budget and the write loop.
2. A host SHOULD serve topics, one per feature (walls, roofs, framing, rebar …), read when needed. Each profile SHOULD ship its own topics.
3. The core SHOULD stay under 41 270 characters and each topic under 25 000, so that a core and a topic fit an agent's context beside its work.
4. Every folder carries AGENTS.md (Part III, 8.2), the conventions an agent cannot read off the files.

Reference: the guide action; guideCore and guideText in src/core/automation/guide/; the size limits are held by tests/guide-topics.test.ts.

8. The headless host

1. An agent host MUST run without a screen or a browser: in a terminal, a CI job, a sandbox or a server.
2. Operations that need a screen (views open on screen, renders) MAY answer that they need one; every operation of section 1's first table MUST work headless.

The reference implementation offers two headless hosts (informative):

ek export   <model> <folder>       write a model as a folder
ek import   <folder> <file.json>   read a folder back into the single-file form
ek validate <model>                check the model; its errors and their fixes
ek request  <model> '<json>'       any request (summary, tree, read, query, execute …);
                                   a write is validated, then saved back to the model
ek ifc      <model> <out.ifc>      the IFC export

ek-mcp <folder>                    the same requests as MCP tools, on stdio
ek-mcp <folder> --http             on a local endpoint

ek loads the model for each call. ek-mcp loads it once and keeps it in memory, writes only the records that change, sees hand edits, holds .eik/lock so that only one engine writes a folder, and answers one request at a time. In the reference host, 2D snapshots work headless; 3D snapshots need a screen.

Reference: server/ek.ts, server/ek-mcp.ts, server/eikSession.ts, server/eikMcpServer.ts.

9. The agent's file export (informative)

Besides the OpenEik folder itself, the reference host can export a folder made for agents that search with code: one file per record with a _derived block beside the record's members (its path, level, bounds, type name and neighbours by id), an _index.json table in every folder, spaces/ with each room and what stands in it, focus.json with the view a person has open, and a README with search recipes. That export is a view of the model, not a model folder: its derived blocks would break Part IV, section 1, if it were written back. The derived layer (Part IV, 1.1) is the place for derived data beside a model.

Reference: src/core/versions/modelFolder.ts.

10. Not yet specified

Capability negotiation (which profiles, operations and budgets a host offers) and proposals as the unit of review are planned; see the open questions. Attribution of each write to the person and the agent is part of the command envelope of 0.2 (Part V, 10), which Part XVII gives: the person by an id, the agent beside them, and what a host checks of each (Part XVII, 4).