# The spreadsheet as an agent surface: how a grid became this build's control plane

slug: the-spreadsheet-as-an-agent-surface · https://miscsubjects.com/a/the-spreadsheet-as-an-agent-surface · tags: build, spreadsheet, agents, provenance · updated 2026-09-02T07:16:07.843Z

A spreadsheet is a grid of addressable cells. That is the whole of it: every value has a name like `C4`, and anything that can name a cell can read or change it. This build now runs an agent inside one. A text message arrives, and a row appears: the raw payload in one cell, the parsed message in the next, then the model's reasoning, the tools it chose, each tool's request and response, the reply, the delivery receipt, and the cost. One message, one row, left to right.

The reason to do this is not presentation. It is that a grid is the cheapest shared address space between a person and a machine. Both parties can see the same cell, name it the same way, and change it. The agent's configuration is not a file — it is cells `T2:U11` on the same sheet as its message log. Changing the model it runs on is typing into `U2`.

## The mechanism

Three moves make it work, and each one is small.

**Every object is projected as a row that carries its own mutation URL.** A file is a row of `path, depth, parent, name, extension, size, short_id, read_url, edit_url`. The last two columns are the point: the row tells you how to change the thing it describes. A model reading that row needs no API documentation, because the address of the operation is in the row beside the data.

**The unit of state is a cell, so a write is a coordinate and a value.** Not a request body, not a schema — `(sheet, row, column, value)`. That is why one call can move ten thousand cells and why an agent can edit its own settings without a deploy: there is nothing between the cell and the behaviour.

**Machine reasoning is stored as parsed structure, not prose.** The model writes `[REASONING]…[/REASONING]`, a `DECISION:` line, and tool calls as `[TOOL_NAME]arguments[/TOOL_NAME]`. A parser reads those out of the raw text and executes them. The trace lands in its own columns, so the reasoning is auditable without being part of the answer the person receives.

## Why tags instead of JSON

A model calling a tool through a function-calling API emits a JSON object the person never sees. Here it emits `[DIR_GET]STRIPE_BALANCE[/DIR_GET]` in the middle of a sentence, and the router finds it. Two properties follow.

It is legible to both parties. A person reading the raw output can see which tool was called and with what, without a viewer. So can the next model.

It is cheap. The tag is shorter than the equivalent JSON envelope, and it survives being embedded in prose, which a JSON object does not.

The cost is a narrower grammar. A tag key must be `A-Z`, `0-9` and underscore, and the closing tag must match. Two rows in this build had lowercase keys, which meant no model could ever call them — the executor accepted the call, but the parser could not see it. Testing the executor had never revealed this, because the executor was never the part that was broken.

## What it can do that Google Sheets and Apps Script can

The design is copied from a working Google Sheets system, and the debt should be stated plainly. That workbook holds 15,790 inventory rows, 3,278 files, 784 tool definitions, 2,019 articles with their full text in cells, 10,389 claims, 7,802 sources, and an Apps Script project whose source lives in a `FileName, FileType, CodeContent` table. It proved the idea before any of this was built.

| Capability | Sheets + Apps Script | This build |
|---|---|---|
| A1 addressing, ranges, values | Yes | Yes |
| Read/write over REST | Sheets API v4 | `/api/sheets/<id>/values/<range>` |
| Row as a button | `onEdit` trigger, ~1 min lag | Write a cell, agent turn fires |
| Code stored in cells | `ProjectCode` tab, by hand | `FILE TREE` with read and edit URLs |
| Formula recalculation | Full dependency graph | **None** |
| Charts, pivots, formatting | Yes | No |
| Concurrent editors | Google's infrastructure | One Durable Object per sheet |
| Per-cell audit with a hash chain | No | Yes, 2.8M events sealed |
| Tool calls from a cell | `=INVOKEALL()` via a bridge | Native, 976 tools |
| Execution time limit | 6 minutes | None; a turn continues across invocations |
| Row-level provenance | Revision history, not in the API | Every write on the chain, addressable |

The honest ledger: Sheets wins on everything a human wants from a spreadsheet, and this build wins on everything a machine wants from one. There is no formula engine here, no charts, no pivots. What there is instead is that every cell change is an event on a hash-chained log, every tool is callable from the surface, and nothing in the loop has a six-minute ceiling.

## Is it a SQL visualizer

Not yet, and the distinction is worth being precise about, because it is the difference between a report and a control plane.

A SQL result grid is a **read projection**. You run a query, you get rows, the rows are dead. Nothing you type into them goes anywhere, and the next run replaces them. Every database GUI works this way.

This is a **read-write projection with identity**. A cell has a stable address, a version, an author, and a path back to whatever produced it. Typing in it changes the object underneath. The nearest established name for the shape is a materialized view with write-through, and the nearest established discipline is incremental view maintenance — keeping a derived table correct as its inputs change.

It could become a SQL surface, and the missing piece is small: a tab whose definition is a query rather than a set of cells, refreshed on a trigger, with the write path mapped back to the source table. The read half already exists — `D1_QUERY` and `LEDGER_QUERY` return rows today, and 976 tool results are already written into a range. What is missing is the binding that says *this range is that query* and keeps them tied.

The thing genuinely absent, and more valuable than SQL, is **reactivity**. `=A1+B1` recomputing when `A1` changes is the one primitive that makes a spreadsheet a spreadsheet rather than a table, and this build does not have it. Without a dependency graph, the grid is a log plus a form. With one, a cell could hold `=DISPATCH("LEADS_ENRICH", A2)` filled down four hundred rows, and four hundred agent turns would become one authored expression. That is the single largest missing feature, and it is the one that would change how much work a person has to do.

## Where it sits in the stack

Below it: Cloudflare D1 for the mirror, one SQLite-backed Durable Object per sheet for single-writer atomic claims and live push, R2 for cells too large to store inline, a hash-chained event log for provenance.

Above it: iMessage, WhatsApp and email arriving as rows; 976 tools, 96 agents and 53 flows callable from the surface; articles whose contents are cells.

The pattern it belongs to is older than spreadsheets in software terms. A Smalltalk image and an Emacs session share the property that matters here: the environment is inspectable and modifiable from inside itself, and there is no separate configuration layer. A spreadsheet is the version of that idea that a person who has never programmed already knows how to read.

## Proof of work

Each of these was measured, not asserted.

Every one of 976 directory rows was fired or contract-checked, and the result written to the sheet at `W1:AC977` with its arguments, milliseconds, raw payload and next action. 401 return live data. 353 were deliberately not invoked because they send messages, move money, delete state or spend on media generation; those were checked for a resolving transport instead. 197 fail, and the sheet names the cause of each.

Every tool was then re-tested through the tag grammar a model must use, against the router's own parser rather than a test harness. 972 of 976 parse with byte-identical arguments. Three cannot be called by any model: `AUDIO` collides with a meta tag the router strips, and two keys contain lowercase letters the grammar cannot match.

Nine gates in the deploy path were found to be invoking a test runner that has never been installed in this repository. Each had failed on every deploy without executing a single assertion, and one of them was reporting a broken guard while the guard was fine. Converted to the runner the runtime provides: 87 assertions now run on every ship.

The transparency chain had not sealed since 12 August and was 1,060,446 events behind, because no row addressed the seal and so nothing could schedule it. It now seals every ten minutes and has advanced past 2.8 million events under its own power.

A configuration change is now replayed against real messages before it can take effect. Swapping the model to a non-reasoning variant produced a correct answer that would never have been sent, because the model wrote plain text instead of the reply tag. The gate refused the change and quoted the failure.

## What would make it better

**A dependency graph**, so a cell can hold an expression that recomputes. Everything else on this list is smaller than this one.

**A range bound to a query**, so a tab is a live view of a table rather than a copy of one.

**Windowed reads at real scale.** The Google workbook's 15,790-row tab is where that product starts to fail, and this build's grid loads a window and pages on scroll — but 50,000 rows has not been tested, only reasoned about.

**Cell-level versions.** Today the audit chain records the event; the cell holds only the current value. Putting the version stack behind the cell is what would let two agents disagree about a value and have both positions survive.

**A public read token**, so a range can be embedded anywhere without a credential. The widget below is a snapshot for exactly this reason.

## The sheet, in an article, in the sheet

The grid below is a range from the live sheet, rendered inside this page with its cell addresses intact. The article you are reading is itself a row in the same workbook — its slug, title and full text sit in cells. So the containment runs both directions, which is the property worth having: the surface can describe itself without leaving itself.