Sheets
A spreadsheet that lives in the workspace: addressable by key, searchable beside your documents, and drivable by an agent. 175 functions, real spill ranges, dependency-ordered recalculation, undo.
6 min
What it is for
And, just as usefully, what it is not.
The thing this does that a general spreadsheet cannot is sit inside a workspace: an agent creates a grid, fills it, reads it back and cross-references it against the documents and tickets that explain it — all without leaving the place the work lives.
QUERY. If you need those, export and use a spreadsheet. If you need a grid your agent can build and read, this is the shorter path.The verbs
Eighteen, and they split cleanly.
sheet-create— A new workbooksheet-get— Read a rangesheet-set— Write cellssheet-append— Add rows to the endsheet-clear— Empty a rangesheet-fill— Fill a range from a seed, series-awaresheet-from-file— Import CSV or TSV
sheet-structural— Insert or remove rows and columnssheet-layout— Column widths, row heights, frozen panessheet-format— Number formats, alignment, coloursheet-sort— Sort a rangesheet-tab— Add, rename or remove a tabsheet-names— Named rangessheet-rules— Conditional formatting rules
sheet-list— The workbooks in this workspacesheet-save— Persist the current statesheet-export— CSV, TSV, HTML or lossless JSONsheet-restore— Roll back to a restore point
Reading without destroying
The one trap that costs data.
as: 'values' and as: 'raw' are lossy reads. They return what a formula evaluated to, not the formula. So a caller that reads with either and writes the result back has silently replaced every formula in the range with a constant — the sheet still looks right, and stops updating.| You want | Use |
|---|---|
| The numbers, to reason about | as: 'values' — fine, as long as you do not write it back |
| A faithful read you may write back | as: 'formulas' |
| A complete copy | sheet-export with format: 'json' |
The CSV, TSV and HTML exports carry computed values and cover one tab — the reply names the tabs it left out rather than quietly flattening the workbook.
Reads are capped, and they say so
On both axes and on total cells.
A read that hits a bound reports which one, and hands back a range that continues where it stopped. A silent cap is the accept-and-ignore failure this product has shipped before; a cap that reports itself is a paging protocol.
beehaven call sheet-get '{"id":"<id>","range":"A1:D200","as":"formulas"}'Formulas
175 functions, and spill behaves properly.
An array formula spills into the cells below and to the right, and a spill that would collide with existing content reports #SPILL! rather than overwriting it. Recalculation is dependency-ordered, so a chain updates in one pass.
=SEQUENCE(4) spills A1:A4 =VLOOKUP(A2, D:E, 2) the usual lookups =SUMIFS(...) the usual aggregates
#REF!, not a silent read of the current sheet. That distinction was a real defect once — a wrong answer that looked like a right one.Do not edit one as a document
document-update can address it — and would replace the grid with prose while returning ok: true. The document verbs refuse a sheet by type now and name the verb that works. Use sheet-set.