Pebble Stream for Agents and Models
This documentation is to enable AI Agents and large language models (LLMs) to understand how to construct Pebble Stream enabled spreadsheets. It introduces a structured JSON syntax for Pebble Stream directive declarations and an alternative lightweight format for representing Pebble Stream enabled spreadsheets.
Why do this?
Today's ecosystem centers on a human in Excel. Compilation happens in the Zen add-in, directives live in cell text inside workbooks, and the authoring surface is a canvas. This initiative lets agents participate in the Pebble Stream ecosystem safely and securely. We do this by enabling the following.
1. A text-native workbook source
Agents write text superbly and manipulate .xlsx badly. We define a plain-text form of a pebble workbook — one file per worksheet (CSV-like, with formulas as text, directives in their usual cells, header comments alongside) plus a small manifest — and make the compiler service accept it as a first-class input, producing the same compiled pebble an Excel workbook would. Zen can export a workbook to this form and import it back, so humans and agents edit the same thing and a Git diff is meaningful. This also solves a governance problem: deployed pebbles are encrypted and immutable, but agent-authored logic needs human review, and reviewable source text is how you get it without weakening the deployed artifact. It sidesteps the POI exposure too, since nothing agent-side ever touches .xlsx.
2. Make the contract machine-readable and the errors machine-actionable
We publish the directive reference as a schema (JSON Schema or similar generated from the same source as the documentation repo), including each directive's arity, allowed targets, and the generative/transformative exclusion rules. Then make every compile, validate, and execution error structured: code, sheet, cell, directive, a one-line fix hint, and a pointer into the schema. The "collect every failure" validate mode you already decided to build is exactly what an agent needs; the retry loop you designed for extraction (deterministic errors fed back to the model) is the same loop for authoring. An agent that gets twenty structured failures in one pass converges; one that gets the first failure per attempt wanders.
3. One front door: an MCP server over the Flow and Board APIs
We wrap compile, validate, dry-run, execute, status, fetch-outputs, fetch-lineage, and Board discovery as MCP tools, served by Flow (or the hosted connector service). Agents already speak MCP; this gives any agent framework the full lifecycle without GSH writing per-framework SDKs. Pair it with a published skill file (the directive schema, worked examples, the text source format, the PFR/PFRT conventions) so an agent arrives knowing the idioms instead of rediscovering them.
4. A build-test-promote loop with no human in the inner loop
Flow's workflow builder already lets a pebbler test before a workflow reaches a Board. We now formalize that as an API: an agent submits source, gets a compiled pebble, runs it against sample inputs in DEV, compares outputs to expected values, and iterates. Require a test set (inputs, expected outputs, or at minimum fail/warn assertions) as part of any agent-submitted workflow — you have deterministic arithmetic checks as a design pattern already; make them mandatory for agent-authored logic. Promotion to QA/UAT/PROD stays under the two-actor rule. That is where the human belongs: once, at the gate, reviewing source and test results, not on every run.
5. Identity, scope, and budgets
You decided outside agents get a service identity. Flesh that out: short-lived tokens scoped to a server, Board, or workflow and to a direction (build, execute, read); per-identity request and row budgets like the Data Service's two-pool budgets; and a hard rule that a service identity can never approve a download or hold an approving business role. We record the agent identity, model, and a hash of the prompt or source on every request so the tamper-evident request record answers "who or what built and ran this."
6. Outputs an agent can reason about
Execution is already asynchronous with real-time outputs. We add a webhook callback alongside polling, return outputs as CSV or PFR with the manifest, and expose the lineage document so an agent processing results can explain a number by tracing it to its inputs rather than guessing. Include the overflow flag, volatile-function warnings, and engine version in the status payload so an agent can decide for itself whether a result is trustworthy.
7. Where humans stay
We keep humans exactly where you have already put them on the Board: output approvals to customers, promotion gates, and pausing. Everything upstream of that — authoring, compiling, testing, DEV runs, result processing — can be agent-driven once the pieces above exist.
Updated about 13 hours ago