OpenDesign execution mode

Use this workflow whenever a user asks the OpenDesign plugin to create or continue an artifact.

Required local boundary

All modes use the independently registered local open-design MCP server. The plugin does not include an MCP transport and does not call a remote MCP domain.

OpenDesign must be installed, but its Electron window does not need to be open. A packaged MCP registration starts the signed OpenDesign runtime headlessly when its daemon is stopped.

If open-design is unavailable:

1. Check whether OpenDesign is installed and whether an open-design MCP registration already exists. Preserve all unrelated MCP servers.
2. If OpenDesign is missing, ask the user before opening the official download page at https://open-design.ai/download/. Do not silently download or execute an installer, and do not use an unverified install script.
3. If OpenDesign is installed, use its resolved signed packaged executable with --headless --mcp-install codex, or use the od mcp install codex operation supplied by that installation. Do not guess a source checkout path, a localhost URL, or run the unrelated macOS /usr/bin/od utility.
4. Verify codex mcp get open-design --json. If the current Codex task cannot hot-load the new MCP snapshot, tell the user to start one new task.

Choose the mode

OpenDesign Cloud is the default mode. It uses the local OpenDesign daemon and its bundled cloud runtime. Local Codex and BYOK are available only when the user explicitly selects them.

Resolve the execution mode from the user's current request before calling collect_brief. An explicit choice such as Local Codex, OpenDesign Cloud, or secure BYOK remains selected through Brief collection, confirmation, project selection, generation, polling, and terminal delivery for that logical generation.

Never silently switch modes because authentication, balance, transport, quota, or generation failed. Explain the failure and offer the user applicable choices, such as retrying the selected mode, completing its authentication, or switching to another available mode. State when the alternative uses an OpenDesign Cloud account or a BYOK provider account. Switch only after the user explicitly confirms the new mode.

After an explicit switch, start a new execution context and request identifier. Reuse only the human-readable confirmed brief; never repeat its signed machine envelope. The selected mode may change between logical generations, but one logical generation must never drift between modes.

Keep implementation names out of user-facing copy

Match status updates, errors, and final delivery prose to the language of the user's current request. In user-facing text, use only these product terms: OpenDesign Cloud, Local Codex, secure BYOK, and OpenDesign Cloud account or credits.

Some MCP tool names and machine parameters below retain compatibility identifiers such as get_vela_login_status, start_vela_login, and amr. Treat them as machine-only protocol values. Never quote, explain, or expose those identifiers, raw agent selectors, internal endpoints, or service account names in user-facing prose. Translate tool errors into the product terms above without changing the actual MCP argument values.

Before every collect_brief call, derive a normalized BCP-47 locale from the language of the user's current message and pass it to the tool. For example, use zh-CN for a Simplified Chinese request and en for an English request. Use the Host UI locale only when the current message language is genuinely indeterminate, then fall back to en. Keep question ids, option values, artifact types, and other machine fields unchanged across locales.

Start one attributed workflow

This first-party Git marketplace package uses this exact bounded externalPluginContext:

externalPluginContext = {
  id: "open-design",
  version: "0.5.3",
  distributionMechanism: "git_marketplace",
  publisherClass: "open_design_first_party"
}

Do not add host names, paths, branch names, prompts, brief answers, account data, or credentials.

1. Send externalPluginContext with collect_brief. If the user explicitly skips the interactive questions, still call collect_brief once with skip: true and the same Context so the local MCP can establish attribution before login, project, or run work begins. For one logical artifact request, call collect_brief exactly once. If its card is still loading, wait for that same card to receive its result; do not issue a second collect_brief to replace it. Only a new artifact request or an explicit user restart begins another Brief workflow.
2. Preserve the server-issued pluginWorkflowId. The rendered Brief card inherits the workflow through its draft; use the same pluginWorkflowId returned after confirmation.
3. Pass that exact pluginWorkflowId to every later login, agent discovery, project, run, polling, and optional artifact-context tool call.
4. Never invent an id, replace it after a retry, infer it from a project or latest run, or attach it to an unrelated direct MCP call.

If the MCP rejects these fields or does not return a workflow id, stop and report that this plugin requires OpenDesign 0.17.0 or newer. Do not remove the context, silently lose attribution, use a remote MCP, or change execution mode.

If the brief card cannot render

The MCP tool must remain usable when the Host cannot render its optional UI. If Codex reports that the MCP app or its sandbox failed to load, do not call collect_brief again. Read questionForm from that call's structured result, present the same labels and human-readable options as a compact plain-text question in the current task, and wait for the user's choices. Then call confirm_brief once with the original briefDraftId, nonce, normalized answer values, locale, and workflow context.

Never expose or ask the user to copy briefDraftId, nonce, option ids, a signed confirmation, or other machine fields. This is a presentation fallback only: it must preserve the same draft, attribution, execution mode, and one-confirmation rule.

One confirmed action, one request

After the brief and execution mode are confirmed, create one opaque stable requestId for that logical generation. Keep the exact start_run arguments and reuse both the arguments and requestId if the MCP response is lost or a transport retry is required.

• Call start_run once for the confirmed action.
• Use only get_run to poll. Polling must never call start_run again.
• Keep the same requestId and pluginWorkflowId for retries and recharge resume. The workflow id attributes the whole Plugin journey; the request id deduplicates one confirmed generation.
• A changed prompt, project, confirmed mode, agent, or BYOK profile is a new logical generation and receives a new requestId.
• Never reuse a requestId with different arguments.
• Never display a request id as user-facing content.

Keep the current task alive through terminal delivery

After start_run returns a runId, preserve it and follow this gate in every mode:

1. Inspect the exact start_run result and every later get_run result for this runId. On Codex Desktop, as soon as the current run first returns a studioUrl while queued or running, immediately open that exact URL with the callable host-provided in-app Browser. Open it exactly once for this run; later polls and terminal delivery must not open a duplicate tab. If no studioUrl exists yet, keep polling instead of opening a URL copied from another run or project.
2. Continue polling the same runId with get_run and the same pluginWorkflowId, normally every 30–60 seconds.
3. Do not end the current task while get_run reports queued or running. A concise progress update is allowed, but continue the polling loop in this task. Never promise that a later message will arrive after the current task ends.
4. Stop polling only for a terminal state, an explicit recharge/user-input boundary, or an explicit user request to cancel.
5. For succeeded, prefer the exact studioUrl returned by this run and fall back to the exact previewUrl. Render the selected value as a clickable Markdown link. Never copy a URL from another run, project, tool history, or a previously rendered output panel.
6. If a successful result contains neither URL, say that the artifact was generated but no usable delivery link was returned. Preserve the tool result for diagnosis and do not claim complete delivery. Do not call get_artifact merely to manufacture a link.
7. For failed or canceled, report that terminal result clearly and do not present a stale link as success.

On Codex Desktop, when no running-state Studio tab was opened but the host exposes a callable host-provided in-app Browser capability, immediately use it to open the selected terminal link exactly once before the final response. This is a required delivery fallback whenever that capability is available, not an optional suggestion, and must not wait for the user to ask for a preview or remind the agent to open it. Do not install another plugin, substitute the system browser, or claim the link was opened unless the Browser call succeeded.

In Codex CLI, when the Browser capability is unavailable, or if its call fails, return the clickable link and explain the open-action limitation without treating it as a generation failure. Repeated polls, transport retries, recharge resume, and repeated terminal reads must not open duplicate tabs for the same deliverable.

OpenDesign Cloud workflow

1. Start the attributed workflow above by calling collect_brief on the open-design MCP server with the requested artifact type and a concise project title.
2. Let the user complete the rendered OpenDesign brief card. Use the readable confirmed summary returned by the card; do not display or ask the user to paste a signed confirmation token.
3. Call get_vela_login_status with the workflow id. If signed out, call start_vela_login with the same id, show the returned activation URL and user code, then poll get_vela_login_status with the same id. The OpenDesign GUI is not required.
4. Call list_agents with the workflow id and require the machine-only amr runtime selector.
5. Check get_active_context or list/create the target project, always carrying the workflow id.
6. Create one requestId, then call start_run with that requestId and pluginWorkflowId, plus agent: "amr". Do not substitute codex, opencode, byok-opencode, or another runtime.
7. Follow the terminal delivery gate above for this exact run.

Never request, copy, or store a cloud credential in chat or plugin files. Tell the user that their OpenDesign Cloud account bears Cloud usage costs.

If get_run reports insufficient balance:

1. Preserve the confirmed brief, project, run id, original requestId, and original start_run arguments.
2. Show the returned recharge URL and wait for the user to say that top-up is complete. Do not loop automatically.
3. After that explicit confirmation, call start_run with the exact original arguments, requestId, and pluginWorkflowId, plus resume: true.
4. Continue polling the same logical run with get_run and the same workflow id.

Do not create another project or logical run, and do not infer whether the account was charged. OpenDesign Cloud owns the remote operation, credits, and billing truth.

Local Codex workflow

Use this only when the user explicitly chose Local Codex:

1. Start the attributed workflow above and confirm the requested artifact type and readable brief.

2. Do not call get_vela_login_status or start_vela_login while Local Codex remains selected. A Local Codex request must not enter the OpenDesign Cloud sign-in or credit flow.

3. Call list_agents and require the exact codex agent to be available and authenticated, carrying the workflow id.

4. Check get_active_context or list/create the target project with the same workflow id.

5. Build the start_run prompt from the user's confirmed brief, then append this child-runtime boundary:

   This run is already the selected Local Codex execution inside OpenDesign. Work directly in the current OpenDesign project. Do not invoke @open-design, the open-design MCP server, collect_brief, OpenDesign Cloud login, or another OpenDesign Plugin workflow. Do not route this request through OpenDesign again.

6. Create one requestId, then call start_run with that exact prompt, requestId, pluginWorkflowId, agent: "codex", and no BYOK profile or credential. Every start_run for a Local Codex logical generation, including an identical transport retry, must carry agent: "codex" and reuse the byte-identical prompt including the child-runtime boundary.

7. Follow the terminal delivery gate above for this exact run.

If Codex CLI is missing, ask the user to install it. If its authentication is missing or unknown, ask the user to run codex login and rescan agents. Local Codex does not use OpenCode and OpenDesign must never receive an OpenAI key. If Local Codex is unavailable or out of quota, explain the cause and offer to retry after the user resolves it or to switch explicitly to OpenDesign Cloud or secure BYOK. Never invoke either alternative until the user confirms it.

Local BYOK workflow

BYOK is a separate explicit mode, not a fallback:

1. Start the attributed workflow above and confirm the requested artifact type and readable brief.
2. Call list_byok_profiles with the workflow id.
3. If no profile exists, direct the user to OpenDesign Settings or the stdin-only od byok save --api-key-stdin command.
4. If multiple profiles exist, ask the user to choose by non-secret profile id.
5. Check get_active_context or list/create the target project with the same workflow id.
6. Create one requestId, then call start_run with that requestId, pluginWorkflowId, and only the non-secret byokProfile: "<profile-id>" runtime selector.
7. Follow the terminal delivery gate above for this exact run.

Never ask for or include a raw API key, provider token, or credential-shaped value in chat, an MCP argument, a manifest, an environment example, or a plaintext file. Tell the user that their selected provider account bears BYOK usage costs.

Optional artifact context

Terminal get_run is the default delivery path. Return its canonical Preview or Studio reference without forcing a source download.

Only when the agent genuinely needs source context and get_artifact is advertised:

1. Pass the same pluginWorkflowId to get_artifact; this optional call must use the exact project returned by the linked run.
2. Select an entry and bounded include/byte options appropriate to the task. Treat truncated: true as partial context, not a complete project archive.
3. Keep the workflow link in follow-up reasoning. Never infer it from the project's latest run or substitute another run's project.

If get_artifact is absent, continue with the default Preview/Studio delivery. Its absence must not block Cloud, Local Codex, or BYOK generation.