# 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:

| Operation | Does | Section |
|---|---|---|
| `summary` | the project at a glance: levels, counts by category and type, what to read next | 2 |
| `tree` | one folder of the model's layout per call | 2 |
| `read` | elements, in tiers, through the filter, paged | 3, 4 |
| `execute`, `execute_batch` | commands, with dry runs (Part V) | 6 |
| `validate` | check the model as it is now, hand edits included | 6 |
| `guide` | the conventions and topics, on demand | 7 |

and SHOULD offer:

| Operation | Does |
|---|---|
| `query` | answer a question (counts, sums, groups, a text search, what a line passes through) without shipping records |
| `snapshot_2d`, `snapshot_3d` | a labelled picture of a view or a 3D region, through the same filter |
| `changes` | what changed since a sequence number or a version |
| `report_problem` | a structured report from the agent about the host or the model |

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:

| Criterion | Keeps |
|---|---|
| `elementIds` | these elements (at most 5000) |
| `categories` | elements of these categories |
| `levelIds` | elements on these levels |
| `hostId` | a host and every element hosted on it |
| `box` `{min, max}` | elements whose bounds meet a world box, in mm |
| `radius` `{elementId, mm}` | elements whose bounds come within `mm` of an element's bounds |
| `viewId` | what a view shows: its hides, category filters, section box and crop |
| `selection` | the element selected in an interactive session, where there is one |
| `changedSince` | elements changed after a sequence number of this session |

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):

```text
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](https://openeik.org/spec/0.2/envelope) gives: the person by an id, the agent beside them, and what a host checks of each ([Part XVII, 4](https://openeik.org/spec/0.2/envelope#4)).