Summon

Summon renders AI-generated UI in an inline Arrow sandbox. The generated UI can only use host tools you register, so the host keeps control of data, actions, credentials, network access, state, and persistence.

The adopter mental model is intentionally small:

Term	Meaning
Surface	The generated UI Summon renders.
Host tool	A host-owned data source or action the surface may request.
Sandbox	The inline Arrow VM and trusted renderer where generated UI runs.
Surface config	The host's choice of what the surface is allowed to do.
Diagnostics	Stream and Devtools information used when something breaks.

In the TypeScript API, a surface config is SurfacePolicy. Summon compiles it into a stricter SurfacePlan plus a read-only SurfaceContractView before any model-authored output is accepted.

Project Status: Beta

Summon is pre-1.0 and under active development. The protocol, generated-surface contract, and public JavaScript exports may change before a stable release.

The public package boundary is:

@anarchitecture/summon
@anarchitecture/summon-server
@anarchitecture/summon-react

Quickstart

pnpm install
cp apps/server/.env.example apps/server/.env
# edit apps/server/.env and set ANTHROPIC_API_KEY, OPENAI_API_KEY, or GEMINI_API_KEY
pnpm dev:gallery

Open http://localhost:5174.

The Surface Gallery is the first OSS demo. It shows static surfaces, host-backed search, host-owned actions, approval flows, direct Arrow composition, and background host work without exposing the maintainer workbench.

For the maintainer workbench:

pnpm dev:workbench

Open http://localhost:5173/generate.

1. Choose the Host resource search showcase scenario.
2. Confirm the agent broker selects an interactive run with only the search host tool allowed.
3. Run it, then submit a generated search such as chicken pasta.
4. Open http://localhost:5173/adversarial and confirm the sandbox boundary still holds.

To steer generation from a Ghost fingerprint, set SUMMON_GHOST_ROOTS in apps/server/.env before starting the demos. Each configured root should use the canonical .ghost/fingerprint/manifest.yml package layout. The Surface Gallery adds a Ghost fingerprint preset for each root, and the Generate workbench adds a Fingerprint · <id> option. A fingerprint run is not a bundled visual direction: Summon consumes the Ghost relay brief as product design direction, then applies host-owned policy, tools, and token CSS.

The full guided path lives in docs/adoption/quickstart.md. The architecture boundary is documented in docs/ghost-fingerprint-architecture.md.

How It Fits Together

Summon's supported integration path is narrow:

1. Register the host tools the surface may use.
2. Choose a surface config for the run.
3. Generate the surface on the server.
4. Render accepted output in the sandbox.
5. Use diagnostics when generation or interaction fails.

The model can propose UI, but it cannot give itself permissions. Generated requests are advisory until the host validates them and dispatches them through registered host tools.

To run both demo apps at once:

pnpm dev:demos

Demo Map

• apps/surface-gallery - primary adopter gallery with curated live presets, compact host tools, Ghost-root presets when configured, an inline Arrow surface, and a small event strip.
• /generate - diagnostic maintainer workbench for broker-selected surface configs, allowed host tools, token overrides, validation summaries, replay, Ghost steering, Devtools, and stream diagnostics.
• /batch - parallel broker harness for prompt coverage, host tool wiring, direction-token visual coverage, throughput, and consistency checks.
• /adversarial - sandbox boundary checks for network, storage, parent access, and unallowed host tool requests.
• /strict - retired overlay note; the current runtime is the inline Arrow sandbox.
• /fatal - retired boot note; current errors surface through the inline Arrow handle and Devtools events.

Public Packages

• @anarchitecture/summon - curated host-authoring helpers, surface config helpers, and explicit subpaths for advanced browser, engine, host, policy, envelope, assets, Devtools, and token CSS APIs.
• @anarchitecture/summon-server - provider-neutral generation lifecycle, Arrow protocol hardening, validation summaries, and model-provider interfaces.
• @anarchitecture/summon-react - SummonSurface React adapter for inline Arrow surfaces. react and react-dom are peer dependencies.

Workspace Map

• packages/summon* - public package facades.
• packages/engine, packages/host, packages/devtools, packages/sandbox-runtime, packages/server, packages/react - private implementation workspaces published only through the public facades.
• apps/server - multi-provider demo server for Anthropic, OpenAI, and Gemini, direction loading, Arrow protocol diagnostics, and demo backing routes.
• apps/surface-gallery - first-run live example app for OSS adopters.
• apps/demo - Vite maintainer workbench for generation, batch runs, adversarial checks, Ghost steering, diagnostics, and retired iframe-era notes.

Adoption Docs

• Quickstart - one golden end-to-end path.
• Integration - minimal host/server wiring with current APIs.
• Package Consumption - how React apps and frameworkless hosts should import built Summon packages.
• Mobile WebViews - web-first requirements for iOS/Android WebView embedding.
• Security Posture - surface types, host rules, and browser-test expectations.
• Debugging - diagnostics for failed generation, broken controls, missing data, runtime errors, and sandbox safety.
• Agent skill - repo-local operating guide for AI agents working on Summon.

Security Boundary

Summon runs generated Arrow logic inside a QuickJS/WASM VM and mutates the page only through Arrow's trusted renderer. The host explicitly chooses the allowed host tools for each run; declarations from generated UI are never executable authority. Generated network access is off by default and product data should flow through host tools.

Run the safety harness before changing the inline runtime, Arrow bridge, generated network policy, or tool-dispatch behavior:

pnpm test:safety

Useful Commands

pnpm typecheck
pnpm test
pnpm test:safety
pnpm test:gallery
pnpm build
pnpm check:public-api
pnpm smoke:public-packages
pnpm pack:dry-run
pnpm dev:gallery
pnpm dev:workbench
pnpm dev:demos
pnpm port-direction <path-to-expression.md> [id]
pnpm eval-directions [--prompts N] [--directions id,id] [--seed N] [--dry]

pnpm test:safety runs the Playwright Chromium and WebKit smoke suite for sandbox containment and generate-page boot. It starts only the Vite demo app and does not require a model-provider API key.