sergeinikolenko/burette/open-workspace

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.

1. 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.

1. 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.

1. 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.

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

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

1. 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.

1. 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.

1. 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.

Desktop handoff links

Desktop opens return result.deepLink. This navigation link reopens the initial files and attaches the same local agent session. It does not serialize camera, unsaved edits, or scene state; use a saved MVSX artifact for portable scenes. Use burette.create_link or burette-agent.mjs link --session-dir <directory> to create another link. Never invent a session ID or include action JSON in URLs.