How the API session works

Transport

The compute_contract_cli processor starts with the --session flag. As its first line, it reports readiness: one JSON line on standard output. After that, the conversation runs line by line — you write one JSON request line to its input, and it answers with one JSON line on output. Requests are processed strictly in order: the next one is read only after the previous one’s response, so you can’t send them in a batch and match responses by number.

The conversation isn’t always one-directional. The processor has no TLS of its own, and for an operation that needs the network over https or a connection to Postgres or SQL Server, it writes you a counter-question — a line with a kind field and its own id — and stops until it gets a response with the same id. You’re the one who has to reach the network, answer, and watch the clock: the deadlineMs in its line is a deadline for you, not a limit the core gives up at on its own. Don’t answer, and it will wait indefinitely; close the input stream, and the operation ends in a refusal. This only happens inside such an operation — exactly when you’re already waiting for its response anyway; an ordinary workbook edit never asks a counter-question.

What kinds of counter-lines there are

There are three conversations in all, and every one starts with a line from the core and ends with your line carrying the same id.

The core writes	What it’s asking for	You respond
transport-request	A single https request: the address, method, headers, deadlineMs	transport-response with status, headers, and the body in bodyBase64 — or transport-error with the value timeout, tls, offline, or connection-reset
socket-open, socket-send, socket-recv, socket-close, socket-cert-hash	A long byte stream to a database: open, send, receive, close, show the certificate fingerprint	socket-opened with the channel number, socket-sent, socket-data (with an eof flag), socket-closed, socket-cert — or socket-error with the same list of causes
credential-proof	A proof of the database password: the core never holds the password itself or anything derived from it	credential-proof-response with proofBase64 and serverSignatureBase64 — or credential-proof-error

Any other line breaks off the operation

While the core waits for a response, it reads exactly one line and expects it to match by kind and id. Everything else — another request, a response with someone else’s id, unparseable JSON — counts as a protocol violation, and the operation closes with a refusal; for a database channel, this poisons the channel itself too. So don’t send anything of your own while a counter-conversation is in progress.

The core reaches out over http on its own: only https is delegated outward.

const child = spawn(binary, ["--session"], {
  stdio: ["pipe", "pipe", "inherit"],
});

child.stdin.write(JSON.stringify(request) + "\n");

Lifecycle

Step	What to keep	Why
open_workbook_subset	payload.subsetId	Identifies the workbook in this process
open_workbook_subset	payload.activeSheet.path	The sheet key: that’s what edit operations expect, not the visible name
apply_cell_edits	payload.workbookHistory.revision	The new accepted revision
every response	ok / code / payload	Every refusal has its own code; you must never show success on ok: false
save_workbook_subset	destinationUri	The full address of the saved file, starting with file://

Important

The subset identifier lives only inside the running process. Don’t store it in your own database and reuse it after a restart: a new process doesn’t know about it, and you need to open the workbook again.

What to do with a refusal

if (!response.ok) {
  throw new Error(response.code + ": " + JSON.stringify(response));
}

Whether to pass expectedRevision

The field is optional, and it determines the behavior on a race.

With it, the core checks the number against the workbook’s current revision. If the workbook was already changed, the request is refused with the apply-cell-edits-stale-revision code and changes nothing — the edit never lands on top of someone else’s.

Without it, the edit applies unconditionally, over whatever the current state is. This is legacy behavior; it suits cases where a single session edits the workbook and concurrent changes can’t happen.

For an integration, pass expectedRevision — the one that came back in the response to the previous operation. A breakdown of the response contents is below on this page.

What arrives in the response

Success and refusal differ by the ok field and by their contents.

Field	When it’s present	What it means
ok	always	true — the operation succeeded, false — it was refused before the workbook changed.
requestId	if it was in the request	The request’s tag, returned unchanged. This is how the response ties to the request — it’s the only reliable way, because the operation name in the response can differ from the one you sent.
payload	when ok: true	The operation’s result; its fields are described on that operation’s own page.
code	when ok: false	A stable refusal code — this is what your handling branches on. There’s no closed list of codes, so a default branch is mandatory.
message	when ok: false	A human-readable reason; this is what’s worth showing in the log.
details	when ok: false	Extra detail, when there is any.
warnings	always	Warnings that don’t cancel the result.
requestedBackend, backendUsed, fallbackUsed	always	Which runtime was requested, which one actually ran, and whether it had to fall back to a different one.
:::

What warnings show up

A warning doesn’t cancel the result — the operation is done. It says the operation was done not quite the way you might have assumed, and two of them change how you should write your code.

Code	What happened	What to do about it
large-sheet-viewport-open	A large sheet is opened by its visible area. Until the sheet is fully loaded, usedRange, maxRow, and maxCol come from a size hint, or, if there isn’t one, describe only the loaded start of the sheet. The total count of filled cells and anything beyond what’s loaded is deferred.	Don’t treat these fields as a description of the whole sheet right after opening. If you need the full picture, wait for the full load, in the same process.
cached-formula-preview	Formula values are shown as Excel last saved them: only the current subset recalculates live.	If you’re presenting the numbers as “ours”, wait for the recalculation first. For viewing, that’s enough.
cached-formula-values-preserved	On save, Excel’s saved formula values carried over as is — you asked for this with the preserveCachedValues: true field.	Nothing; this way the numbers in the file are preserved even where we didn’t recalculate. The field has no default — you have to state a value every time.
cached-formula-values-omitted	Those same values were dropped on save — because you asked for that.	Confirm that whatever reads the file can recalculate: without the values, it will see empty formulas.
requested-backend-unavailable	You asked for a different engine than the one running; it computed with the one available.	Check backendUsed. There won’t be a refusal — it will quietly compute somewhere other than where you thought.

Next

• The example’s requests, step by step — Requests used in the example.
• If something isn’t working — Diagnostics.