Apex Operator and tool-led building

Simple terms

Operator is the AI builder. It uses browser, page, code, selector, network, screenshot, filesystem, and persistence tools to help build and QA experiments.

Apex Operator is the model-led experiment builder. It gives the model compact tools for inspecting pages, network traffic, state, selectors, artifacts, QA evidence, and persistence.

Routes

• /experiments/[id]/variations/[varId]
• Operator logs overlay in the variation editor
• /api/operator-chat-session
• /api/operator-events
• /api/operator-runs
• /api/operator-evidence
• /api/operator-network
• /api/operator-screenshot

Implementation behavior

• On installed stores, Operator browser tools can use an active on-site editor session to inspect and interact with the real merchant page instead of the proxy iframe.

• The compact on-store dock can generate and save a treatment from live DOM context. Full tool-led QA, evidence review, and launch gating remain in the dashboard Operator workflow.

• Operator sessions gather current experiment, variation, page, workspace, and store-profile context.

• Tools let the model inspect DOM, network, console, page state, selectors, files, screenshots, artifacts, and saved preview state.

• Operator writes structured changes to variation mutations or code workspaces instead of relying on one-off text suggestions.

• Operator never puts attached image data into variation code. In variant build mode, it uses upload_asset for an image from the current turn and puts the returned hosted URL in the variation.

• External handoff now prefers the Apex CLI workflow: install @drip-apex/apex-cli, run apex login, check out canonical workspace files, dogfood with apex workspace dev, then publish with apex workspace publish.

• The CLI uses the same canonical workspace file model as in-app Operator: src/index.js, src/index.scss, src/info.js, src/mutations.json, experiment.config.json, targeting.json, goals/*.json, segments/*.json, network/*.recipe.json, and dev-doc.md.

• Workspace goal sync: adding a goal to a paused or running test no longer blocks saving code edits; the build now re-syncs workspace goal files from the database when appropriate (see docs/specs/spec-6654-workspace-goal-sync-heal.md).

• Logs preserve chat messages, tool calls, evidence, failure states, artifacts, and network details for review.

• The product principle is general tool affordance first: avoid hardcoding one test type as the only supported workflow.

How to use it

• Use Operator to inspect a target page, propose a variant, build it, and collect QA evidence.
• Review every generated change before launch.
• If a model variation finishes just after the run budget expires, it is now saved as a draft (not discarded); the run failure card shows the draft state and a retry option.
• Operator runs now persist every observed event and record their exit branch; uploads finalize once expected events arrive, recover missing events by sequence, and retain capture sequences after clearing logs.
• Open the in-editor logs overlay when a run fails, produces unexpected output, or needs auditability.
• Give Operator specific constraints, but let it use general tools for page inspection and implementation.
• For handoff runs, let the external agent inspect the live target URL and relevant storefront/domain context itself; screenshots are useful evidence, not a hard prerequisite.

When not to use it

• Do not treat Operator output as automatically launch-safe.
• Do not use it for deterministic one-click workflows that normal forms already handle faster.
• Do not constrain Operator to one narrow playbook when a general page-inspection tool can solve the task better.

Implementation source

• Core code lives under src/features/apex-operator.
• APIs include /api/operator-chat-session, /api/operator-events, /api/operator-runs, /api/operator-evidence, /api/operator-network, and /api/operator-screenshot.
• The variation editor mounts the Operator UI and uses saved tool results to persist mutations, code workspace changes, artifacts, and evidence.
• External handoff uses @drip-apex/apex-cli with apex workspace checkout, apex workspace dev, and apex workspace publish against canonical workspace files shared with in-app Operator.

Data and API

• APIs include /api/operator-chat-session, /api/operator-events, /api/operator-runs, /api/operator-evidence, /api/operator-network, and /api/operator-screenshot.
• CLI workspace APIs include /api/v1/experiments/[id]/variations/[variationId]/workspace, file read/write routes, build, and revisions.
• Models include operator sessions, events, artifacts, evidence, review records, and code workspace snapshots.
• Uses store profile facts, assets, backlog context, experiment setup, and preview browser state.

Failure modes

• Poor output usually means missing target URL, missing store context, or vague instruction.

• Tool failure can come from blocked storefront access, auth-required pages, CSP, or preview host mismatch.

• A disconnected on-site tab falls back to the dashboard preview transport; reopen Edit on store when real-origin verification is required.

• Never assume generated code is launch-ready without QA and visual inspection.

• Operator preview limits: storefront pages up to 8 MB now load in the visual editor preview; when a page cannot be loaded the Operator turn ends quickly (within about one minute) and shows a simple failure message instead of a long timeout.

• Operator evidence and reads: Operator now collects page evidence in parallel with a 20 second deadline per read so a slow storefront does not stall a build for minutes.

• Preview preparation: the visual editor prepares the preview once per Operator turn instead of before every model call, reducing repeated work during a single turn.

• Inspection behavior: Operator no longer substitutes slow host-component or commerce-surface reads for the model's inspection calls; when evidence is missing the model is informed instead, and successful host-context reads clear subsequent missing-evidence hints.