SinabinaandClaude Opus 4.8
cb1792fc58
Reconcile the four integrated v2 runtime implementations (unified execution result contract, execution profiles, capability readiness, GitHub security) with main's browser-provider hardening. Conflict resolutions: - runtimeContract() generator: keep new execution-result + doctor-capability paragraphs, adopt main's `[matching browser flags]` fallback wording; regenerate the six RUNTIME.md. - package.json: keep the strict isolated test:gstack2 runner and marked 18.0.6 security bump; adopt main's playwright-core alias. - bun.lock: regenerated via bun install. - release-hardening.test.ts: adopt main's browser-provider assertions (resolveServerLaunchTarget, --browser managed smoke loop). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
7.2 KiB
Optional runtime capabilities
The six Agent Skills are useful without a GStack runtime. Never install, download, build, select, update, or remove runtime capabilities merely because a skill was invoked.
Before interactive browser work, read references/BROWSER-PROVIDERS.md in full. It owns host-provider detection, consented host setup, and the common readiness journey. The GStack fallback uses the local Playwright adapter with one explicit engine choice; skill installation never proves browser readiness.
When an active specialist first reaches a capability it cannot use, name the exact capability and why it is needed. Offer to continue without it when the judgment-only or host-native path remains valid. Before any network preview, ask whether the user wants to check official setup options and exact sizes. Disclose that an uncached preview makes one public GitHub request for signed manifest metadata and sends no repository content, private URL, file, cookie, token, or credential; then STOP. A cached already-verified manifest may preview offline, but never silently fetch.
For a browser-backed capability, first run node references/support/runtime-bootstrap.mjs options --capability <name>. This local-only command performs no network request or mutation. Show the detected installed Chromium executables plus managed Chromium, explain that either choice uses an isolated automation profile, and STOP for a choice. Never infer or silently record one. Installed Chromium avoids browser-binary downloads; managed Chromium is isolated and reproducible. Internal browser-visible requires managed Chromium because installed Chrome-family builds can block automation extension loading.
Only after the user approves the metadata check and, when applicable, chooses a browser engine, run the non-mutating preview from this skill root: node references/support/runtime-bootstrap.mjs preview --capability <name> --browser managed or node references/support/runtime-bootstrap.mjs preview --capability <name> --browser installed --browser-path <absolute-path> (repeat --capability for additional requested capabilities). Omit browser flags for capabilities that do not depend on a browser. It dependency-expands, reports already verified local components, exact missing components, and their summed compressed bytes. It never downloads components or mutates runtime state. Preview consent is not install consent.
User-facing setup capabilities are exactly browser, design, diagram, pdf, and ios. all means those five and intentionally excludes visible Chromium. The internal browser-visible capability is additive and is offered only when a workflow actually reaches a headed browser, extension, or browser-handoff step. Never offer it during ordinary headless QA.
After showing the complete preview, STOP for explicit approval. Only after approval run the matching install command with the same capabilities and browser flags plus --yes; install must reprint the identical dependency-closed plan before downloading. The approved browser choice is then persisted atomically in $GSTACK_HOME/config.json. gstack config browser clear disables browser-backed launchers; the managed/installed config commands can reselect only a provider compatible with the active slot. Switching providers requires a fresh preview and install so configuration cannot point at a runtime missing that engine. Signed internal components are core, browser-code (adapter code and dependencies), browser-headless (managed Playwright headless shell and FFmpeg), browser-visible (managed full Chromium), design, diagram, pdf, and ios. With managed Chromium, logical browser expands to browser-code + browser-headless; with an installed browser, the same logical capability downloads browser-code only and the stable launcher injects the validated executable path. Internal browser-visible expands to browser-code + browser-visible and is managed-only. diagram depends on logical browser; pdf depends on diagram; ios is Darwin-only. The manifest schema is v2 with global capabilityComponents and componentDependencies, plus targets[target].components[id] carrying signed exact-byte artifacts.
The dependency-free Node 18+ bootstrap accepts only official GStack GitHub Release hosts, validates manifest/runtime/skill API/platform/component metadata and SHA-256, verifies a declared Cosign bundle when Cosign is available, rejects unsafe archive paths/links, and invokes the atomic managed installer. Never run ./setup inside a standard-installed skill directory, enroll a host, or treat skill installation as runtime consent.
After doctor confirms readiness, canonical launcher bindings are GSTACK_HOME=${GSTACK_HOME:-$HOME/.gstack}, GSTACK_BIN=$GSTACK_HOME/bin, BUN_CMD=$GSTACK_BIN/bun, B=$GSTACK_BIN/browse, D=$GSTACK_BIN/gstack-design, and P=$GSTACK_BIN/make-pdf. Specialist modules may bind only the launchers they use. These assignments do not install or grant consent. Never download or install a second Bun for GStack helpers; the managed runtime owns its pinned Bun executable in the active slot.
Some retained helpers are shell scripts. gstack doctor verifies Bash and, on Windows, discovers Git for Windows Bash; disclose and stop at the affected helper if that prerequisite is unavailable. Python is not a global GStack prerequisite: only a specialist flow explicitly labeled as Python-dependent may request it, at the point of use and with the user's approval.
The package/runtime compatibility tuple is schemaVersion=1, runtimeVersion=2.0.0, and skillApi=2.0; the machine-readable copy is references/support/runtime-contract.json. An incompatible active runtime is unavailable, not permission to upgrade it.
Every optional-runtime tool result must satisfy references/support/execution-result-contract.json before it is presented as success. Success requires non-empty evidence. Empty or malformed output and explicit degraded, unsupported, or failed statuses remain non-success with stable codes; human renderings must preserve that status and code.
Use gstack doctor --capability browser|design|diagram|pdf|ios (optionally --json) for a non-mutating, capability-specific readiness result. Its independent axes must remain distinct: pure judgment availability, platform support, preview consent, install consent, and runtime readiness. Readiness is exactly ready, degraded, unavailable, unsupported, or failed. Doctor never grants or persists consent, previews metadata, or installs anything. unavailable means setup may be offered; failed means selected runtime evidence failed; unsupported is a platform boundary; and degraded means the capability passed while the managed runtime has a warning.
The developer-only fallback is node references/support/runtime-bootstrap.mjs install --source <reviewed-checkout> --capability <name> [matching browser flags] --yes; show its trust warning and use it only when the user explicitly selects a checkout they reviewed. If the packaged bootstrap is unavailable, stop capability setup instead of guessing a checkout-relative command. Deferring installation records no consent and must not block pure judgment.