Skip to content

Commit ab5f3e8

Browse files
DavidBabinecDavidBabinec
authored
feat(agent): add document-targeted site tools
* feat(agent): add document-targeted site tools * fix(agent): update snapshot token benchmark read surface
1 parent 6988c18 commit ab5f3e8

36 files changed

Lines changed: 1173 additions & 699 deletions

‎docs/features/agent.md‎

Lines changed: 42 additions & 25 deletions
Large diffs are not rendered by default.

‎docs/features/templates.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -363,7 +363,7 @@ The site-scope AI agent can author templates end-to-end:
363363

364364
1. Build the chrome on a page with `insertHtml`, including one `<instatic-outlet>` element where the wrapped content should appear (the importer maps it to a `base.outlet` node).
365365
2. Call `setPageTemplate(pageId, target, priority?)` — `target` is `{ kind: 'everywhere' }` or `{ kind: 'postTypes', tableSlugs: [...] }`. For a postTypes target, the agent reads valid slugs from `list_post_types` first.
366-
3. `clearPageTemplate(pageId)` reverts a template to an ordinary page. `list_pages` reports each page's current `template` config.
366+
3. `clearPageTemplate(pageId)` reverts a template to an ordinary page. `list_documents` reports each page/template's current `template` config.
367367

368368
No outlet save-guard applies here either — an agent-built template with no outlet simply doesn't apply. See [agent.md → Templates](agent.md) for the tool surface.
369369

‎docs/reference/architecture-tests.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -156,7 +156,7 @@ See [docs/features/plugin-system.md](../features/plugin-system.md).
156156
| Test | What it enforces |
157157
|-----------------------------------------------|----------------------------------------------------------------------------------|
158158
| `agent-no-raw-html-in-reply-rule.test.ts` | The agent system prompt contains the narrate-only rule (1–2 sentence replies, no raw HTML/CSS/JSON in the reply body). Prevents accidental removal during prompt refactors. |
159-
| `agent-system-prompt-no-module-enumeration.test.ts` | The system prompt does not enumerate module ids — they're discovered via `list_modules`/`read_page` at runtime. Also asserts the HTML-native style markers (`insertHtml`, "Structure as HTML, styling as CSS"). |
159+
| `agent-system-prompt-no-module-enumeration.test.ts` | The system prompt does not enumerate module ids — they're discovered via `list_modules`/`read_document` at runtime. Also asserts the HTML-native style markers (`insertHtml`, "Structure as HTML, styling as CSS"). |
160160
| `agent-tool-surface.test.ts` | Legacy node-construction tools (`insertNode`, `insertTree`) and retired class-patch tools (`createClass`, `updateClassStyles`) are absent from the site write-tool list; HTML-native replacements (`insertHtml`, `getNodeHtml`, `replaceNodeHtml`) and the unified CSS-authoring tool (`applyCss`) are present; design-system token tools and template tools are present; total count is exactly 22. |
161161

162162
### AI infrastructure

‎scripts/bench/README.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -164,12 +164,12 @@ You'll get a frame-by-frame scrubber with DOM snapshots, network waterfall, cons
164164
### snapshot-tokens (opt-in)
165165
Measures how many tokens the site-editor agent's page **read surface** costs, comparing the two representations of the same page:
166166

167-
- **JSON** — the legacy read surface (deleted): `inspect_page` (full node tree) + `list_classes` (all CSS classes) + `list_tokens` (design tokens), each `JSON.stringify`'d exactly as the old tools emitted them into a `tool_result`. Rebuilt by a local `flattenForBench` that reproduces the deleted `buildPageSnapshot` node/class/token mapping, so this regression guard keeps measuring the surface that `read_page` replaced.
168-
- **read_page** — the live first `read_page` result from `renderAgentPage(...)`, counted as the exact serialized tool payload including `pageInfo`. It contains annotated body HTML with a `uid` on each tag plus page-relevant CSS wrapped in a `<style>` block. The CSS includes framework variables/utilities, font token variables, active-page module CSS, used class rules, applicable ambient selectors, and page-targeted user stylesheets. It omits browser-only `@font-face` blocks, unrelated cross-page ambient selectors, long base64/data URLs, and very long URLs. Oversized pages report `pageInfo.nextPart` so follow-up `read_page({ part })` calls can retrieve the remaining cleaned slices.
167+
- **JSON** — the legacy read surface (deleted): `inspect_page` (full node tree) + `list_classes` (all CSS classes) + `list_tokens` (design tokens), each `JSON.stringify`'d exactly as the old tools emitted them into a `tool_result`. Rebuilt by a local `flattenForBench` that reproduces the deleted `buildPageSnapshot` node/class/token mapping, so this regression guard keeps measuring the surface that `read_document` replaced.
168+
- **read_document** — the live first `read_document` result from `renderAgentDocument(...)`, counted as the exact serialized tool payload including `pageInfo`. It contains annotated body HTML with a `uid` on each tag plus page-relevant CSS wrapped in a `<style>` block. The CSS includes framework variables/utilities, font token variables, active-page module CSS, used class rules, applicable ambient selectors, and page-targeted user stylesheets. It omits browser-only `@font-face` blocks, unrelated cross-page ambient selectors, long base64/data URLs, and very long URLs. Oversized pages report `pageInfo.nextPart` so follow-up `read_document({ part })` calls can retrieve the remaining cleaned slices.
169169

170-
Tokens are counted with Anthropic's `count_tokens` endpoint (model-accurate, no SDK) against the **real seeded pages** in `.tmp/dev.db`. The report gives per-page and aggregate JSON-vs-read_page token counts and a ratio, plus fairness/fidelity facts it deliberately surfaces: how many `@media` breakpoint blocks the counted CSS carries, how many nodes got annotated, and how many carry per-node prop overrides that live in the JSON tree but not in the published CSS (responsive styling that flows through included class `@media` blocks is counted on the read_page side).
170+
Tokens are counted with Anthropic's `count_tokens` endpoint (model-accurate, no SDK) against the **real seeded pages** in `.tmp/dev.db`. The report gives per-page and aggregate JSON-vs-read_document token counts and a ratio, plus fairness/fidelity facts it deliberately surfaces: how many `@media` breakpoint blocks the counted CSS carries, how many nodes got annotated, and how many carry per-node prop overrides that live in the JSON tree but not in the published CSS (responsive styling that flows through included class `@media` blocks is counted on the read_document side).
171171

172-
The HTML read surface has shipped (`read_page` replaced the five legacy JSON tools). This bench now serves as a **regression guard** — confirming the first size-budgeted read remains cheaper than the legacy JSON surface it replaced. It is **opt-in**: it needs `ANTHROPIC_API_KEY` and a seeded dev DB, and it makes one network call per measured string. Run it with:
172+
The HTML read surface has shipped (`read_document` replaced the five legacy JSON tools). This bench now serves as a **regression guard** — confirming the first size-budgeted read remains cheaper than the legacy JSON surface it replaced. It is **opt-in**: it needs `ANTHROPIC_API_KEY` and a seeded dev DB, and it makes one network call per measured string. Run it with:
173173
```bash
174174
ANTHROPIC_API_KEY=sk-... bun run bench --only=snapshot-tokens
175175
```

0 commit comments

Comments
 (0)