v1.81.0.0 feat: Aside is the browser gstack drives first; every browsing skill, the PDF/diagram renderer, and web research; the bundled browser stays the automatic fallback (#2810)

* feat(aside): browser-driver contract, cookbook, research and fallback resolvers {{ASIDE_SETUP}} (readiness probe + ten rules for driving the user's real browser), {{ASIDE_COOKBOOK}} (script shapes verified live against Aside CLI 1.26: one flow per aside repl script, CDP console hook before navigation, evidence lines, session-directory artifact handoff, GSTACK_STEP_OK sentinel), {{ASIDE_RESEARCH}} (research through aside exec, WebSearch when Aside is absent, knowledge otherwise) and {{BROWSE_FALLBACK}} (the fifteen-row Aside-step to $B-command table plus the rules that differ, so every browsing skill keeps working on gstack's own headless browser). test/aside-driver.test.ts pins the sentences and asserts every browsing skill carries the Aside block followed by the fallback; test/helpers/aside-available.ts is the shared live-Aside probe. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * feat(render): Aside-first local-HTML renderer with the bundled browser as fallback lib/aside-render.ts serves the HTML's directory on loopback (Aside refuses file:// URLs), opens it with waitUntil load, prints through CDP Page.printToPDF so tagged output, outlines, header/footer templates and page numbers survive, emulates device metrics for sized screenshots, and writes in-page evaluations to files; when Aside is absent it runs the same spec through the browse daemon (newtab, load, js, pdf, screenshot, closetab) and reports ENGINE=aside|browse. bin/gstack-render.ts is the CLI skill templates call. lib/claude-bin.ts and lib/error-handling.ts become the canonical copies (browse/src re-exports them). Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * refactor(browse): /browse drives Aside first, with the $B reference behind the fallback Contract, cookbook, mode choice (aside repl by default, aside exec for reading), report format, the fallback section, and the full command reference carved on demand. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * refactor(qa): /qa and /qa-only drive Aside, fall back to $B QA_METHODOLOGY runs every phase as Aside scripts (orient, explore, document, re-test, mobile viewport via CDP emulation, links via HEAD fetch); the authenticate phase is 'you are already signed in'; a 13th rule requires consent before mutating actions on non-local targets; the fallback section translates each step onto $B. The qa E2E tests run on whichever engine is present. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * refactor(design): design-review, design-consultation, design-shotgun, plan-design-review, design-html drive Aside Design-system extraction is one script printing FONTS/COLORS/HEADINGS/TOUCH_TARGETS/NAV; competitor research confirms the exact URLs before opening them in the real browser and runs on the bundled browser when Aside is absent; design-html's viewport screenshots, sketches and comparison boards render through gstack-render. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * refactor(deploy): benchmark, canary, land-and-deploy Step 7, devex-review drive Aside One aside repl script per page prints NAV/PAINT/LCP/RESOURCES/SCRIPTS/CSS/SUMMARY (benchmark), CONSOLE_ERRORS/NAV/TEXT + screenshot (canary, re-run every 60s), and the post-deploy check reads responseStatus from the navigation entry; each carries the $B fallback. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * feat(third-party-actions): Aside is the recommended driver; gstack's visible browser stays the fallback The readiness probe is lifted from {{ASIDE_SETUP}} at gen time (byte-identity pinned) and rule 3 points at browse/SKILL.md for how to drive; the consent question offers Aside first and gstack's own visible browser (handoff/resume for sign-in) as the fallback, as v1.72 framed it. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * refactor(scrape): /scrape reads pages through Aside; the browser-skills runtime rides the fallback Look-then-extract scripts build the JSON inside the page and print it between JSON_START/JSON_END; aside exec for fuzzy intents; on the $B fallback the browser-skills match/prototype flow and /skillify apply as before. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * refactor(make-pdf): print through Aside first, the bundled browser otherwise asideClient.ts replaces the direct $B client with one render() call per PDF (the exact option mapping the browse pdf command had: paper, margins, header/footer/page numbers, tagged, outline, printBackground, preferCSSPageSize, Paged.js wait); the diagram pre-pass, oversized-image downscale and DOCX rasters each run as one render script with per-fence try/catch; exit 4 now means no browser is available and names both remedies; $P setup reports which engine it found. The e2e gates run on whichever engine is present, so the Linux lane exercises the fallback. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * refactor(diagram): the triplet is one gstack-render call SVG, PNG and excalidraw from one invocation over the content-addressed bundle staged under /tmp/gstack-render; every diagram type gets an excalidraw export; gstack-render picks the engine and prints ENGINE=; the diagram E2E gates on either engine. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * feat(research): web research runs in Aside first, WebSearch second The planning, review, design, security and investigate skills research through {{ASIDE_RESEARCH}}; WebSearch stays in allowed-tools as the fallback; testing.ts's bootstrap step follows; skeleton ceilings ratcheted for the research block. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * feat(setup,gen-skill-docs): prune renders of skills that no longer exist setup gains _prune_stale_generated for every host tree and the doc generator removes gstack-* output dirs it did not write, so a skill removed from the source tree can never linger in an install. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * test: registries, budgets and suite reconciled for Aside-first with the $B fallback Touchfiles + E2E tiers gain the Aside keys, coverage matrix and eval baselines updated, size budget re-baselined to parity-baseline-v1.80.0.0.json (the contract plus fallback ride in every browsing skill), parity ceilings ratcheted with measured values, LLM-judge prompts and the E2E fixtures speak Aside-first, browse-fallback. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * docs: Aside first, gstack browser fallback README, BROWSER.md, docs/, CONTRIBUTING, CLAUDE.md, ARCHITECTURE, AGENTS.md, TODOS and the root router describe the one product story: Aside is the browser gstack drives first; the bundled headless browser is the automatic fallback (Linux, Windows, app closed) where cookie import, GStack Browser, pair-agent and browser-skills still apply. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * chore: regenerate SKILL.md docs, llms.txt, agents digest, ship goldens, context-budget fixture bun run gen:skill-docs over the templates; goldens re-rendered; context-budget ceilings recaptured. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * v1.80.0.0: Aside is the browser gstack drives first; the bundled browser is the fallback MINOR: new capability across ten skills, the renderer and research; nothing removed. CHANGELOG release summary + itemized changes; VERSION 1.80.0.0; package.json 1.80.0. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * docs(todos): file non-Claude host ownership-gate and version-heading pin follow-ups Two follow-ups from the /plan-ceo-review + /plan-eng-review pass on merging PR #2804 with main's v1.80.0.0 ownership gate: bring the Codex/Factory/ OpenCode/Cursor/Kiro copy loops and the stale-render prune under the .gstack-owned marker rule, and a free test pinning that the CHANGELOG top heading equals VERSION (the collision that git cannot see). Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * fix: pre-landing review fixes for the Aside-first branch Review army + adversarial passes (Claude and Codex) on the merged branch: setup - _prune_stale_generated scans the host dirs too (the generator already removed the render before setup ran, so the host branch was dead), skips symlinks in the render tree (rm -rf on a slash-terminated link empties its target), removes a host symlink only when it resolves into gstack, cleans a bannered real dir through _cleanup_weak_dir, recognizes frontmatter-renamed skills, and logs through log. The always-run codex render passes every host dir that may link to it. - NEEDS_BUILD checks all three binaries (with $_EXE) and lib/ sources; the browser hint and the bootstrap summary honor GSTACK_SKIP_ASIDE, treat a requested skip as a request, and derive one skill list. lib/aside-render.ts + bin/gstack-render.ts - The loopback server carries a per-render secret path, checks containment on the real path (symlink escapes are 403), and rejects malformed encoding. - Inline eval results are one base64 line, so page text cannot forge ASIDE_DIR= or the sentinel; the last ASIDE_DIR wins. - runProc escalates SIGTERM to SIGKILL, bounds every wait, and clears every timer (an uncleared one kept gstack-render alive after printing OK). - renderTmpDir refuses a shared /tmp name owned by someone else; the work dir and server are created inside try; goto's budget follows the render budget. - probeAside classifies a present-but-failing CLI as ASIDE_NOT_RUNNING like the skills' bash probe; render() retries on gstack's own browser when Aside could not start or its private CDP bridge is gone (never on a page error or a timeout of a running script); the CLI reports the engine that actually rendered, exits 0 on --help, rejects non-numeric flags, documents --wait-timeout, fences EVAL/PAGE_ERRORS as untrusted content, and names the daemon's cookie-import JS lock remedy. - The browse path passes --scale only when asked (a scale change rebuilds the daemon context) and restores the viewport after a sized screenshot. resolvers / templates - The bash probe honors GSTACK_SKIP_ASIDE and has a perl deadline on stock macOS; .local is no longer LOCAL (mDNS); same-origin filters compare parsed origins; link status is HEAD-checked only on LOCAL targets; every aside exec goes through the receipted _aside_exec prelude ({{ASIDE_EXEC_PRELUDE}}), including nine template blocks that called it bare; the design sketch and diagram staging use private directories. - The generator prunes only bannered renders and never a host whose generation failed. Docs, stale comments and dead code cleaned; goldens re-rendered; tests updated and added for every behavior above. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * test: coverage for the render CLI, setup rebuild check, make-pdf exit codes, and prose $B spans New free tests from the ship coverage audit: test/gstack-render-cli.test.ts (argv guards, --help, output contract with a fake daemon, failure and serve-root paths, no-browser case, prompt exit), test/setup-needs-build.test.ts (every binary and source set flips NEEDS_BUILD, Windows suffixes), make-pdf/test/cli-exit-codes.test.ts and setup-smoke.test.ts (error to exit code mapping, runSetup stages, renderPdf's engine), and prose-span cases for extractBrowseCommands in test/skill-parser.test.ts. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * docs: CHANGELOG and TODOS cover the review fixes (v1.81.0.0) Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * docs: sync project docs with the v1.81.0.0 review fixes BROWSER.md, ARCHITECTURE.md, CONTRIBUTING.md, README.md, CLAUDE.md, docs/TESTING_INTERNALS.md and docs/PROJECT_STRUCTURE.md now describe the shipped renderer and setup: the loopback render server's per-render secret path and real-path containment, ENGINE= naming the engine that actually rendered (mid-run retry on gstack's own browser), EVAL/PAGE_ERRORS fenced as untrusted content, --wait-timeout and the CLI's argv guards, the receipted _aside_exec prelude ({{ASIDE_EXEC_PRELUDE}} in the placeholder table), the LOCAL host rule without .local, LOCAL-only HEAD checks in the links script, GSTACK_SKIP_ASIDE across probe/renderer/setup, the ownership-gated retired-skill prune, the widened NEEDS_BUILD check, and the new free tests (gstack-render-cli, setup-prune-stale-generated, setup-browser-hint, setup-needs-build, make-pdf cli-exit-codes and setup-smoke). Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * docs: CHANGELOG states the precise mid-run retry rule Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * fix(test): skill-e2e-bws slices the $B setup block from the Browser fallback section browse/SKILL.md no longer has '## SETUP' / '## Core QA Patterns' (Aside is the primary driver; the $B block moved under 'Browser fallback'), so the gate test sliced an empty block and handed the agent nothing to run. Anchor on '### Find the `$B` binary' up to the next heading. 7/7 pass. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * fix(test): gate POSIX-only fixtures off Windows windows-free-tests: the gstack-render CLI tests drive a shebang fake browse that CreateProcess cannot exec, and two NEEDS_BUILD cases assert an execute bit and a bare-name miss that MSYS bash does not have (test -x ignores mode bits and resolves design -> design.exe). Those describes and cases now self-skip on win32; argument guards, --help, the no-browser case, and every other rebuild-check case still run there. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * fix(render): runProc waits for the exit code until the kill deadline; newtab retries once on a cold daemon A process whose pipes have reached EOF is exiting, but runProc gave the exit code only five seconds to arrive and then returned null, which run() reports as a failed command. Under CI's six-shard load one such render failed with the artifact already written. The SIGTERM/SIGKILL timers already bound the wait, so the exit race now runs to the kill deadline. The first CLI call auto-starts the browse daemon; on a cold start it can answer 'Unable to connect' once while the server is still coming up. That single case is retried after 1.5s; every other newtab failure is not. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * test(aside-render): warm the daemon before live fallback cases; failures name the render error - Live fallback cases run 'goto about:blank' up to twice before asserting and skip (never fail) when the daemon cannot come up. - expectOk() puts r.error and the browse transcript into the assertion so a failed render is diagnosable from the CI log. - The argv-contract cases dump the fake's log on a miss. - File default timeout is 30s: the subject is the CLI contract, not latency. - Two cases pin the cold-daemon newtab retry and that other errors are not retried. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * docs: CHANGELOG notes the cold-start tolerance of the bundled-browser renderer Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> --------- Co-authored-by: Sina <sdroid674+github@gmail.com> Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-16 18:05:31 +02:00 · 2026-09-06 08:54:25 -07:00
parent c241216637
commit 0530392821
172 changed files with 12044 additions and 4676 deletions
@@ -86,19 +86,30 @@ gone: `TREE_MUTATING` is empty (gen-skill-docs has a main() guard and
 docs/TESTING_INTERNALS.md). Never type bare `bun test` for the suite: it
 walks the whole repo, loading paid eval files and missing the strict
 classifier.
-It covers skill validation, gen-skill-docs quality checks, and browse
-integration tests. `bun run test:evals` runs LLM-judge quality evals and E2E
-tests via `claude -p`. Both must pass before creating a PR.
+It covers skill validation, gen-skill-docs quality checks, browse
+integration tests, the Aside contract pins, and the render-wrapper pins.
+`bun run test:evals` runs LLM-judge quality evals and E2E tests via
+`claude -p`. Both must pass before creating a PR. Anything that needs Aside
+itself (`test/skill-e2e-aside.test.ts`, the Aside qa/design E2E cases, the
+live render in `test/aside-render.test.ts`) runs only on a Mac with the Aside
+app open and self-skips elsewhere (`asideAvailable()`). make-pdf's render
+gates and `test/skill-e2e-diagram.test.ts` run through whichever engine
+resolves (`browserAvailable()` — Aside, or the browse binary CI builds with
+`bun run build:gates`) and skip only when neither exists; the fallback
+engine's own tests run everywhere.

 ## Project structure

 Full annotated tree: [docs/PROJECT_STRUCTURE.md](docs/PROJECT_STRUCTURE.md).
-Quick map: `browse/` headless-browser CLI, `design/` design binary,
-`hosts/` typed host configs, `scripts/` build+DX tooling (gen-skill-docs,
-resolvers), `test/` validation+evals, `lib/` shared libraries, `bin/` CLI
-utilities, `extension/` Chrome extension, one directory per skill
-(`ship/`, `review/`, `qa/`, ...), `.github/` CI, `contrib/` contributor
-tools, `docs/designs/` design documents.
+Quick map: `browse/` gstack's own headless-browser CLI (the fallback
+engine) plus the `/browse` skill, `design/` design binary, `make-pdf/` PDF
+binary, `hosts/` typed host configs, `scripts/` build+DX tooling
+(gen-skill-docs, resolvers — `resolvers/aside.ts` is the Aside contract),
+`test/` validation+evals, `lib/` shared libraries (`aside-render.ts` renders
+local HTML through Aside, falling back to the engine), `bin/` CLI utilities
+(`gstack-render.ts` is the render CLI skills call), `extension/` Chrome
+extension, one directory per skill (`ship/`, `review/`, `qa/`, ...),
+`.github/` CI, `contrib/` contributor tools, `docs/designs/` design documents.

 ## SKILL.md workflow

@@ -117,8 +128,14 @@ Codex config.toml pins a different model, rerun `./setup --host codex`
 afterwards to restore your profile (single-owner persistence is filed in
 TODOS.md).

-To add a new browse command: add it to `browse/src/commands.ts` and rebuild.
-To add a snapshot flag: add it to `SNAPSHOT_FLAGS` in `browse/src/snapshot.ts` and rebuild.
+Browser steps in skills are `aside repl` scripts per
+`scripts/resolvers/aside.ts`, each with its `$B` equivalent for the fallback
+engine. To add a new browse command: add it to `browse/src/commands.ts` and
+rebuild. To add a snapshot flag: add it to `SNAPSHOT_FLAGS` in
+`browse/src/snapshot.ts` and rebuild. Local-HTML rendering in a skill template
+is a `bun run ~/.claude/skills/gstack/bin/gstack-render.ts` call; new render
+options go into `lib/aside-render.ts` (which handles the fallback), never into
+a skill's own bash.

 **Token ceiling:** Generated SKILL.md files trip a warning above 160KB (~40K tokens).
 This is a "watch for feature bloat" guardrail, not a hard gate. Modern flagship
@@ -201,8 +218,23 @@ writing-style was extracted to V1.1 — see `docs/designs/PACING_UPDATES_V0.md`.

 ## Browser interaction

-When you need to interact with a browser (QA, dogfooding, cookie setup), use the
-`/browse` skill or run the browse binary directly via `$B <command>`. NEVER use
+gstack drives the Aside AI browser (macOS 15+) first and falls back to its own
+browser engine when Aside is absent. When you need to interact with a browser
+(QA, dogfooding, inspecting a page), use the `/browse` skill: it probes Aside
+and, on `READY`, drives it — the user's real browser with their real sessions —
+through `aside repl` scripts that follow the contract in
+`scripts/resolvers/aside.ts` (`{{ASIDE_SETUP}}`). Every browser skill (`/qa`,
+`/qa-only`, `/design-review`, `/canary`, `/benchmark`, `/scrape`) does the same,
+and web research in skills runs through Aside's agent (`{{ASIDE_RESEARCH}}`)
+before the WebSearch tool. When the probe says `NEEDS_ASIDE` or
+`ASIDE_NOT_RUNNING` (Linux, Windows, a closed Aside app), the skill resolves
+`$B` per `{{BROWSE_FALLBACK}}` and runs the browse binary instead — `$B <command>`
+is a legitimate tool in that context, and cookie import, GStack Browser headed
+mode, `/pair-agent`, and browser-skills/`/skillify` belong to it. Local HTML a
+skill generated itself (make-pdf, diagram, design previews) renders through
+`bin/gstack-render.ts` / `lib/aside-render.ts`, which serve the file on
+loopback and print or screenshot it in Aside, or in the engine when Aside is
+absent — never point the renderer at a site. NEVER use
 `mcp__claude-in-chrome__*` tools — they are slow, unreliable, and not what this
 project uses.

@@ -226,7 +258,10 @@ dashboards, git-class ops). The new-sink scanner in
 `git push` / `fetch` to a non-loopback host unless the file carries a reasoned
 entry in its `SCANNER_EXEMPT` list (user-directed page fetches, reachability
 probes, instruction strings, skill prose) — if you add a new off-machine sink,
-wire it through the helpers and add it to the enumerated sink list. Inspect with
+wire it through the helpers and add it to the enumerated sink list. `aside exec`
+(a gstack-composed prompt sent to Aside's agent) is a fail-open user-facing
+sink: skills call it through the `_aside_exec` wrapper that
+`scripts/resolvers/aside.ts` renders, never bare. Inspect with
 `bin/gstack-egress` (`list` | `verify`, exit 3 on tamper | `grants`). Threat
 model: forensic observability of ATTEMPTED egress, not an exfiltration control.

@@ -255,18 +290,28 @@ Names are either short (`qa`) or namespaced (`gstack-qa`), controlled by
 skip the interactive prompt.

 **Ownership gate (#2119):** `setup` writes a `.gstack-owned` marker into every
-skill directory it creates, and `setup` (the linker, the alias installer, and
-both prefix-flip cleanups) and `bin/gstack-relink` only delete or link over an
-entry they can prove is gstack's. Strong proof (a symlink resolving into gstack,
-or the marker) allows deleting or refreshing the whole directory. Weak proof (a
+skill directory it creates, and `setup` (the linker, the alias installer, both
+prefix-flip cleanups, and the retired-skill prune) and `bin/gstack-relink` only
+delete or link over an entry they can prove is gstack's. Strong proof (a
+symlink resolving into gstack, or the marker) allows deleting or refreshing the
+whole directory. Weak proof (a
 real SKILL.md byte-identical to the source, or carrying gen-skill-docs' two-line
 banner) covers only that one file, and a weakly-proven file that differs is
 moved to `~/.gstack/backups/skills/<ts>/<skill>/SKILL.md` before gstack links
 over it. Anything else is a foreign skill: skipped, and named in setup's final
 summary. The rule lives in two copies (`setup` and `bin/gstack-relink`); keep
-them in sync until the shared helper filed in TODOS.md lands. Pinned by
-`test/setup-link-ownership.test.ts`, `test/setup-cleanup-orphans.test.ts`, and
-`test/relink.test.ts`.
+them in sync until the shared helper filed in TODOS.md lands. The retired-skill
+prune (`_prune_stale_generated`) applies the same strong/weak split to renders
+of skills that no longer exist, through its own gate
+(`_owned_for_windows_refresh`: a real host directory is a candidate only when
+its SKILL.md carries the generated banner; the marker and byte identity are not
+consulted): it scans the render tree and every host skills dir,
+deletes a real render directory, removes a host symlink only when it resolves
+into gstack, cleans a bannered real directory through `_cleanup_weak_dir`,
+never follows a symlink inside the render tree, and recognizes a skill renamed
+through its frontmatter `name:`. Pinned by `test/setup-link-ownership.test.ts`,
+`test/setup-cleanup-orphans.test.ts`, `test/setup-prune-stale-generated.test.ts`,
+and `test/relink.test.ts`.

 **Note:** Vendoring gstack into a project's repo is deprecated. Use global install
 + `./setup --team` instead. See README.md for team mode instructions.
@@ -368,7 +413,7 @@ Before fixing any finding, read [docs/SLOP_SCAN.md](docs/SLOP_SCAN.md):
 it separates genuine quality fixes (empty catches around file ops → 
 `safeUnlink()`, process kills → `safeKill()`) from linter gaming we
 reject (string-matching error messages, tightening best-effort cleanup).
-Utilities live in `browse/src/error-handling.ts`. Don't chase the score.
+Utilities live in `lib/error-handling.ts`. Don't chase the score.

 ## Community PR guardrails

@@ -726,6 +771,7 @@ restore them across all your projects' Claude sessions. It's idempotent.
 Or copy the binaries directly:
 - `cp browse/dist/browse ~/.claude/skills/gstack/browse/dist/browse`
 - `cp design/dist/design ~/.claude/skills/gstack/design/dist/design`
+- `cp make-pdf/dist/pdf ~/.claude/skills/gstack/make-pdf/dist/pdf`

 ## Skill routing