Open Workspace

Use this workflow to open local structures, SDF collections, trajectory bundles,
or workflow result bundles in Burette.

Workflow

1. Run Burette preflight through user-context.
2. Choose mode:
   • auto for the default agent path. It starts browser-agent-shell when
     the full Browser UI is available and falls back to browser-preview when
     the shell cannot start.
   • browser-agent-shell when the user asks for the normal Browser UI, right
     or bottom docks, sidebars, tabs, files/projects, or app-like browser
     behavior. This is the full agent-owned Browser application shell and should use a
     URL shaped like
     http://127.0.0.1:<port>/?devFiles=<encoded absolute path>&agentLayout=focus.
     The focus layout closes the outer left, right, and bottom panels initially
     while keeping their toggle controls available.
     This mode prefers the prebuilt apps/desktop/dist bundle served by
     scripts/agent-shell-server.mjs; in a source checkout without that bundle,
     it falls back to vp dev.
   • browser-preview when the task needs the tokenized agent transport,
     typed MCP/CLI observe and act, quick visual QA, screenshots, or a
     localhost preview without the full app shell.
   • desktop-app when the user asks for the real Burette application or wants
     results left open in the app.
3. For auto, call the CLI and use the returned mode:

bun scripts/burette-agent.mjs open --mode auto <file>

If the result mode is browser-preview, inspect result.fallback before
deciding whether the task still satisfies the user request. Preview fallback is
acceptable for opening/observing a molecule; it is not a substitute for a task
that explicitly needs app chrome such as tabs, docks, or sidebars.

4. For browser-agent-shell, navigate the Codex in-app Browser to the
   agent-owned full Browser shell URL returned by the CLI. The CLI must start
   a fresh local port for this agent session; do not reuse another Browser tab,
   a user-provided Browser development port, or an already-running app unless the user
   explicitly asks to attach to that exact surface.

bun scripts/burette-agent.mjs open --mode browser-agent-shell <file>

Use the returned URL shaped like:

http://127.0.0.1:<fresh-port>/?devFiles=<url-encoded absolute file path>&agentLayout=focus

Open that URL only through the Codex in-app Browser plugin. Do not start a
separate tokenized agent preview only to get sidebars, the right dock, or the
bottom dock.

Opening a folder as one Mol* scene

By default every path becomes its own Burette tab. When the user wants a set of
related structures compared in a single viewer — a folder of simulation stages,
docked poses, or model variants — pass --scene with a folder or with two or
more files:

bun scripts/burette-agent.mjs open --mode browser-agent-shell <folder> --scene structureAll

That returns a URL shaped like
http://127.0.0.1:<port>/?devDocking=<newline-separated paths>&devScene=structureAll&agentLayout=focus,
which opens one combined Mol* scene instead of one tab per file. Use
structureAll to start with every structure overlaid and structurePoses to
start on a single structure. In the scene the user can step through structures,
pick one by file name, and press Align to superimpose them.

Keep the returned sessionDir. In agent shell mode, observe and act use
the same CLI session contract as desktop app mode:

bun scripts/burette-agent.mjs observe --session-dir <sessionDir>
bun scripts/burette-agent.mjs act --session-dir <sessionDir> '{"type":"focus_ligand","selector":{"comp_id":"PYZ"},"allowAmbiguous":true}' --wait-ms 12000

Use manage_burette_tabs for tab strip work inside Burette:

• list to read tab ids, indexes, paths, titles, and active state;
• focus, next, or previous to switch active Burette tabs;
• open_file to open a file as a Burette tab in the existing workspace;
• new to create a blank Burette tab;
• close to close a Burette tab by id, index, path, title, or the active tab;
• move to reorder a tab with toIndex.

Do not open additional Codex Browser tabs when the user asks for additional
Burette tabs.

Use manage_burette_structure_component instead of manually driving the
right-click menus when the user asks to select, focus, hide/remove from view,
restore, or open a structure part separately:

• select or focus with component, chain, compId, seq, or element;
• hide or show for polymer, ligand, water, or ion component classes;
• clear to clear the active Mol* selection;
• open_as_tab to extract a PDB component to a temporary PDB and open it as a
  Burette tab in the same workspace.

This is view/runtime control. Do not delete or rewrite the user's source file
unless they explicitly ask for file mutation.

Use open_burette_docking_view when the user asks for a docking view inside
the existing Burette workspace. Pass receptorPath, ligandPaths, and
optionally sceneMode: "structureAll" when the request is to show structures
together rather than pose-paged docking. Do not use a new Codex Browser tab for
this; it must create a Burette tab in the current workspace.

If the visible in-app Browser tab is already on the agent-owned
browser-agent-shell URL but sessionDir is missing from the conversation, pass
the URL directly:

bun scripts/burette-agent.mjs observe --url 'http://127.0.0.1:<port>/?devFiles=...'
bun scripts/burette-agent.mjs act --url 'http://127.0.0.1:<port>/?devFiles=...' '{"type":"focus_ligand","selector":{"comp_id":"PYZ"},"allowAmbiguous":true}' --wait-ms 12000

The CLI resolves the live shell session through
/__burette/agent-session/session.json and fails quickly when the shell port is
dead.

5. For browser-preview, create the preview URL without launching any external
   browser, then open that URL only through the Codex in-app Browser plugin:

bun scripts/burette-agent.mjs open --mode browser-preview <file> --no-launch

Use the returned tokenized URL with Browser. Do not use macOS open, Arc,
Chrome, Safari, or another external browser for Browser preview unless the user
explicitly asks for an external browser. If the in-app Browser is unavailable,
report a typed blocker instead of falling back to an external browser.

Use the returned tokenized URL when typed agent control is required. Use it as
the auto fallback for molecular opening/observation, but do not treat it as
equivalent to the full browser agent shell when the user is asking about
ordinary Burette UI chrome.

6. For desktop-app, open through the CLI:

bun scripts/burette-agent.mjs open --mode desktop-app <file> --session-dir <dir>

7. Run observe after the workspace URL is open. Completion requires all of
   the following for a Mol* document:

   • observe.activeDocument.ready === true;
   • observe.viewerAgent.available === true;
   • observe.viewerAgent.ready === true and
     observe.viewerAgent.viewerReady === true when those fields are present;
   • no VIEWER_NOT_READY or viewer-agent error.

   An HTTP server starting, a tool process exiting zero, an Inspector summary,
   or correct atom/residue counts does not prove that Mol* rendered the
   structure. If openAsTab was requested, the file-open action must also
   succeed; creating the derived file alone is only partial completion.

8. Read the structure summary:

   • open_burette_workspace returns structureSummary for the opened file.
   • If attaching to an existing workspace or if summary is missing, call
     summarize_burette_structure with file, url, or sessionDir.
     Use this summary internally to understand the file format, molecular kind,
     atom/residue/chain counts, ligand instances, water, ions, and available
     selectors before choosing viewer actions. Do not show explanatory UI text to
     the user just because the summary was read.

9. If visual confirmation matters, use visual-qa.

Handoff

Report the mode, session directory, active document title, viewer readiness,
concise structure facts from structureSummary, and any typed errors. For
every Browser mode, include the exact URL returned by open as a clickable
Markdown link in the final handoff, for example
[Open Burette in Browser](http://127.0.0.1:<port>/...). Include this link even
when the in-app Browser tab is already open and visually verified. A link to
the source file, bundle directory, report, or screenshot does not replace the
Browser workspace link. Do not describe a successful molecular load until the
full readiness gate above passes. When the user wants to see the result, also
require the nonblank central-canvas check from visual-qa; counts are not a
substitute.