feat(integrations): add the local Open Design Cloud flow for Codex by open-design-crew[bot] · Pull Request #6055 · nexu-io/open-design

open-design-crew · 2026-07-24T11:20:16Z

Why

Use case: Product wants Codex Desktop and Codex CLI users to install Open
Design support, confirm a brief, and generate a real Open Design artifact using
Cloud/Vela, Local Codex, or Local BYOK.

Pain: Open Design already has the product runtime, local MCP, projects,
runs, artifacts, agent adapters, and Vela CLI integration, but Codex users must
wire those pieces manually. The previous version of this branch also expanded
the task into a separate remote MCP, Cloud runtime, tenant store, and local
billing system. That duplicated existing ownership, obscured the real local
runtime prerequisite, and made the patch too large to review safely.

This branch has therefore been rebuilt from the latest main. The corrected
boundary is:

Codex -> local Open Design MCP -> local headless OD daemon
      -> Cloud/Vela (`agent: "amr"`)
      -> Local Codex (`agent: "codex"`)
      -> Local BYOK (secure profile reference)

Vela remains the remote identity, wallet, charging, idempotency, and generation
owner. No remote Open Design MCP is introduced.

What users will see

When complete, Codex users will get an Open Design brief card, choose one of the
three explicit execution modes, and receive a real Open Design artifact.

Open Design must be installed, but its Electron GUI does not need to be open.
An installed daemon is started headlessly when needed.
A missing runtime is offered through a user-confirmed official installation
path.
Cloud mode starts Vela browser sign-in through the local Open Design daemon.
Local Codex reuses codex login.
BYOK passes only a non-secret secure-profile id.
Confirming a brief shows readable selections rather than a long opaque token.
No mode silently falls back to another.

The first corrected slice now adds od amr login plus local MCP
start_vela_login / get_vela_login_status, reusing the existing Vela routes
and bundled CLI resolution. Manual activation URL/code is surfaced when the
browser cannot open automatically.

Surface area

UI — new page / dialog / panel / menu item / setting / empty state in apps/web or apps/desktop (including Electron menu bar)
Keyboard shortcut — new or changed
CLI / env var — adds od amr login
API / contract — reuses existing /api/integrations/vela/* routes; no new HTTP contract in the current slice
Extension point — distribution assets live in nexu-io/open-design-agent-plugins, not this repository
i18n keys — added new translation keys
New top-level dependency — no new root dependency
Default behavior change — current slice is opt-in
None — internal refactor, docs, tests, or translation update only

This checklist will be updated as the remaining slices land on this same PR.

Screenshots

No UI surface is present in the corrected first slice. Codex Desktop brief and
generated-artifact evidence will be attached after those flows are implemented
and exercised.

Bug fix verification

This is a feature and scope correction, not a standalone bug fix. The first
slice was still developed red-first:

apps/daemon/tests/amr-login-cli.test.ts
apps/daemon/tests/mcp-vela-login.test.ts
Both suites failed on latest main (6 failures) before the source change and
pass on this branch (6 tests).

Validation

mise exec -- corepack pnpm --filter @open-design/daemon exec vitest run -c vitest.config.ts tests/amr-login-cli.test.ts tests/mcp-vela-login.test.ts --reporter=verbose — 2 files / 6 tests passed
mise exec -- corepack pnpm --filter @open-design/daemon typecheck — passed
Focused existing daemon regression (mcp-runs, message-center-cli, integrations/vela.routes) — 3 files / 100 tests passed
mise exec -- corepack pnpm guard — passed

Full workspace validation and real-host smoke remain pending until the
dependency-ordered implementation is complete.

Reviewer guide

Review the corrected implementation in this order as commits arrive:

Local Open Design daemon bootstrap and MCP registration.
Brief collection/confirmation and MCP Apps resource.
Vela login/status tools and start_run(agent: "amr").
Local Codex and secure BYOK mode routing.
Local request/run deduplication plus the explicit Vela protocol boundary.
Canonical Codex distribution assets in
nexu-io/open-design-agent-plugins.

Do not review for a remote MCP, a second Cloud project/runtime store,
subject-isolated local Cloud tenants, or a second billing ledger; those are no
longer part of this PR.

Remaining acceptance

Unfinished work will continue on this same PR. Do not merge it yet.

lefarcen · 2026-07-24T11:24:02Z

🧪 This PR introduces user-facing flow changes that need a manual QA pass before merge — please hold off merging for now; we'll loop QA in once the PR is merge-ready.

github-actions · 2026-07-24T11:25:01Z

🚀 Landing page preview

This PR is deployed to a Cloudflare Pages preview — not staging or production:

Stable alias: https://pr-6055.open-design-landing-staging.pages.dev
This build: https://3b576b05.open-design-landing-staging.pages.dev
Updated for commit bf6fa63.

mrcfps

@app/open-design-crew Thank you for the substantial work here—the capability isolation, durable Cloud workflow, secure-profile boundary, contracts, and focused coverage are thoughtfully assembled. I reviewed all changed ranges and verified the workspace guard, workspace typecheck, and the focused new daemon suites locally. One primary Preview-path issue needs correction before merge: the capability response currently prevents verified interactive prototypes from running. I also left two merge-safe follow-ups around secure-profile mutation consistency and CLI parity for keyless providers.

_{🔁 Powered by Looper · runner=reviewer · agent=codex · An autonomous AI dev team for your GitHub repos.}

github-actions · 2026-07-24T12:07:41Z

Visual regression review

Head: bf6fa63 · Base: 99c13e0

⚠️ 1 case(s) failed during diff generation; partial captures are shown below.

0 changed · 0 unchanged · 0 new without baseline · 1 failed

Capture or diff failures

visual-capture: No PNG screenshots found in /home/runner/work/_temp/visual-combined/visual-screenshots. Check the Playwright capture logs for details.

Visual diff is advisory only and does not block merging.

mrcfps

@app/open-design-crew Thank you for the substantial follow-up and for adding focused coverage around the local MCP and plugin packaging paths. I reviewed the full current changed range and verified the workspace guard/typecheck plus focused daemon, contracts, plugin-runtime, tools-pack, and Cloud E2E suites. This head introduces an additional primary-flow blocker by making the default Cloud plugin require a running local Open Design app, contrary to the linked issue and the PR's stated use case. The prior unresolved Preview CSP blocker in apps/daemon/src/routes/cloud-capabilities.ts also remains applicable because that code is unchanged on this head.

_{🔁 Powered by Looper · runner=reviewer · agent=codex · An autonomous AI dev team for your GitHub repos.}

mrcfps · 2026-07-24T13:16:34Z

+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.
+
+If `open-design` is unavailable, explain that Open Design must be installed and
+running. Ask the user to install or repair the Codex MCP registration from Open
+Design Settings → MCP server or by running `od mcp install codex`. Do not invent


Blocking — keep the default Cloud install independent from Electron and the local daemon. These lines now require every mode to use an independently registered local open-design MCP and tell users to install and run the Open Design app. That directly contradicts both the linked #6054 acceptance criterion and this PR's current Why section, which require the plugin to work without installing or launching the desktop app; #6054 also explicitly rejects requiring the local daemon. With the bundled .mcp.json removed and the package validator now enforcing this local boundary, a fresh Codex plugin installation has no Cloud transport, so it cannot collect the brief, authenticate, or generate—the primary flow fails before its first tool call. Please restore the production remote HTTPS Cloud MCP/OAuth path as the default plugin transport and reserve the local stdio MCP for explicitly selected Local Codex/BYOK modes, updating the manifest, package contract/validator, docs, and installation tests together. If the product boundary has intentionally changed, it needs a maintainer-approved scope decision rather than shipping as fulfillment of #6054.
_{🔁 Powered by Looper · runner=reviewer · agent=codex · An autonomous AI dev team for your GitHub repos.}

mrcfps

@app/open-design-crew Thank you for rebuilding this into a focused local Vela-login slice—the CLI/MCP reuse and the config-path sanitization are clear and well covered. I reviewed all four changed files and verified the two focused suites, daemon typecheck, and workspace guard locally. I left one merge-safe safety-metadata correction for the new MCP tools.

_{🔁 Powered by Looper · runner=reviewer · agent=codex · An autonomous AI dev team for your GitHub repos.}

mrcfps · 2026-07-24T14:56:03Z

+    annotations: { ...WRITE_ANNOTATIONS, title: 'Sign in to Open Design Cloud' },
+  },
+  {
+    name: 'get_vela_login_status',
+    description:
+      'Check whether Open Design Cloud (Vela/AMR) browser sign-in is complete. Does not expose Vela credentials.',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    annotations: { ...READ_ANNOTATIONS, title: 'Check Open Design Cloud sign-in' },


Non-blocking — mark these Cloud-auth tools as open-world interactions. Both definitions inherit openWorldHint: false, but their changed handlers cross the local daemon boundary: start_vela_login launches Vela device authorization and may open the user's browser, while get_vela_login_status calls /api/integrations/vela/status, whose logged-in path can invoke the Vela billing/account probe. MCP clients may use this annotation when deciding how to present consent or whether a tool is safe to run under a closed-world policy, so describing remote authentication/account access as local-only understates the effect. Please override both annotations with openWorldHint: true (while preserving the current read-only/write and idempotency hints), and assert that value for both tools in mcp-vela-login.test.ts so future shared-annotation refactors cannot regress it.
_{🔁 Powered by Looper · runner=reviewer · agent=codex · An autonomous AI dev team for your GitHub repos.}

mrcfps

@app/open-design-crew Thank you for the focused rebuild and the careful coverage around the shared brief catalog, local confirmation store, MCP Apps resource, and Vela login surfaces. I reviewed all 10 changed files and verified the focused daemon/contracts suites, package typechecks, workspace guard, and full workspace typecheck locally. The earlier merge-safe Vela safety-annotation thread remains open; I added one new merge-safe MCP Apps capability-handling issue below.

_{🔁 Powered by Looper · runner=reviewer · agent=codex · An autonomous AI dev team for your GitHub repos.}

mrcfps · 2026-07-24T15:12:03Z

+            await request("ui/update-model-context", {
+              content: [{ type: "text", text: payload.summary }],
+              structuredContent: payload,
+            });
+            await request("ui/message", {
+              role: "user",
+              content: [{ type: "text", text: prompt }],
+            });


Non-blocking — honor the host capabilities before publishing the confirmation. The initialization result advertises updateModelContext and message independently, but this branch records only a boolean standardBridgeReady and then always awaits ui/update-model-context before sending ui/message. On a valid MCP Apps host that supports server tool calls and follow-up messages but omits context updates, confirm_brief has already made the draft immutable, this first request rejects, and the readable follow-up is never posted; retrying only repeats the same failure. The prompt sent by the next request already contains the full summary, so please retain result.hostCapabilities from ui/initialize, call each optional method only when its capability is advertised, and let a supported ui/message proceed even when context updates are unavailable. Add a bridge fixture where initialization returns serverTools + message without updateModelContext, then assert that submit still reaches ui/message after the successful tools/call. The capability split is defined in the MCP Apps host-capabilities contract: https://apps.extensions.modelcontextprotocol.io/api/interfaces/app.McpUiHostCapabilities.html
_{🔁 Powered by Looper · runner=reviewer · agent=codex · An autonomous AI dev team for your GitHub repos.}

mrcfps

@app/open-design-crew Thank you for the substantial follow-up—the headless MCP bootstrap wiring, focused tests, and data-root propagation are thoughtfully assembled. I reviewed all 20 changed files and verified the workspace guard, full workspace typecheck, and focused daemon, packaged, and contracts suites. One primary packaged lifecycle blocker remains: after Codex starts the windowless runtime, a normal Open Design launch exits after a no-op focus request, so the user cannot open the GUI until that headless owner is stopped. The two existing merge-safe Vela-annotation and MCP Apps capability threads also remain open.

_{🔁 Powered by Looper · runner=reviewer · agent=codex · An autonomous AI dev team for your GitHub repos.}

mrcfps · 2026-07-24T15:57:14Z

+      const request = normalizeDesktopSidecarMessage(message);
+      switch (request.type) {
+        case SIDECAR_MESSAGES.STATUS:
+          return { pid: process.pid, state: "running", url: webUrl, updatedAt: new Date().toISOString() };
+        case SIDECAR_MESSAGES.SHUTDOWN:
+          setImmediate(() => {
+            void shutdown().finally(() => process.exit(0));
+          });
+          return { accepted: true };
+      }


Blocking — let a normal app launch replace or surface the headless owner. This new desktop IPC handler reports state: "running" but handles only STATUS and SHUTDOWN. The normal packaged entry calls inspectExistingDesktopForLauncher; after confirming the daemon and web sidecars are healthy, that function sends SHOW and exits whenever the IPC request resolves. normalizeDesktopSidecarMessage accepts SHOW, so this switch falls through and the JSON IPC server still returns a successful response, which the launcher records as existing-focused even though this process intentionally created no BrowserWindow. As a result, once Codex auto-starts Open Design headlessly, clicking the installed Open Design app produces no UI until the headless runtime is stopped. Please make the windowless owner explicit and have the normal launcher shut it down and continue (or promote it into a windowful desktop) while retaining one owner for the sidecars. Add a lifecycle test that starts with a healthy headless STATUS, sends the normal launch's SHOW, and asserts that a windowful launch proceeds rather than exiting as focused.
_{🔁 Powered by Looper · runner=reviewer · agent=codex · An autonomous AI dev team for your GitHub repos.}

mrcfps

@app/open-design-crew Thank you for the substantial, carefully tested follow-up across the local brief flow, packaged bootstrap, and secure BYOK profiles. I reviewed all 51 changed files and verified 440 focused tests, the workspace guard, and the full workspace typecheck. The existing primary packaged lifecycle blocker remains on this head: in apps/packaged/src/headless-runtime.ts, the windowless owner still accepts the normal launcher's SHOW request without surfacing a window, so a normal Open Design launch exits after Codex has bootstrapped the headless runtime. The existing MCP Apps capability-negotiation and Vela open-world annotation threads also remain. I added two merge-safe BYOK follow-ups below for keyless CLI parity and profile-metadata reconciliation. Thanks again for the thoughtful security boundary and broad test coverage. 🙏

_{🔁 Powered by Looper · runner=reviewer · agent=codex · An autonomous AI dev team for your GitHub repos.}

mrcfps · 2026-07-24T16:34:04Z

+      if (!providerBaseUrl) {
+        return fail('--base-url must be an HTTP(S) URL without credentials, query, or fragment');
+      }
+      if (!parsed.booleans.has('api-key-stdin')) {


Non-blocking — allow the CLI to save keyless BYOK profiles. The new shared request contract and credential service support requiresApiKey: false, and the web flow uses that path for a local Ollama endpoint, but this branch unconditionally rejects od byok save unless --api-key-stdin is present and then hard-codes requiresApiKey: true. That leaves a supported Local BYOK configuration reachable from the UI but not from the required CLI surface. Please add an explicit mutually exclusive keyless flag such as --no-api-key, skip stdin in that mode, send requiresApiKey: false, update the usage text, and cover both the keyless success path and conflicting flags in tools-byok-cli.test.ts.
_{🔁 Powered by Looper · runner=reviewer · agent=codex · An autonomous AI dev team for your GitHub repos.}

mrcfps · 2026-07-24T16:34:04Z

+      byokCredentialTail: undefined,
+    };
+  }
+  return {


Non-blocking — reconcile the selected profile's metadata, not only its credential bit. The daemon response carries the authoritative protocol, baseUrl, model, and optional apiVersion, and the new CLI can update those fields while preserving the same profile id. This branch only flips byokCredentialConfigured/keyTail, so after such an update the browser can keep showing its stale provider and model while ProjectView sends only the id and the daemon runs with the newer profile metadata. That makes Settings and run analytics disagree with the runtime actually used. Please either project the matched profile's non-secret metadata into the active API config during hydration, or invalidate the selected id when the metadata differs and require explicit reconfirmation. Add a state-config test where the same profile id returns a changed base URL/model and assert the chosen reconciliation behavior.
_{🔁 Powered by Looper · runner=reviewer · agent=codex · An autonomous AI dev team for your GitHub repos.}

mrcfps

@app/open-design-crew Thank you for the careful idempotency follow-up—the durable request mapping, conflict response, recharge recovery shape, and focused tests are a strong step forward. I reviewed the full current changed range and verified the workspace guard, full workspace typecheck, and 478 focused daemon, packaged, web, and contracts tests. I found two current-head idempotency gaps around crash recovery and fingerprint completeness. The previously opened headless SHOW lifecycle thread also remains unresolved; this reviewer has reached the REQUEST_CHANGES cap, so I’m leaving this follow-up as a COMMENT for maintainer judgment. Thanks again for the thoughtful implementation and broad coverage. 🙏

_{🔁 Powered by Looper · runner=reviewer · agent=codex · An autonomous AI dev team for your GitHub repos.}

mrcfps · 2026-07-24T17:00:55Z

+    if (!runsLogDir || typeof id !== 'string' || !id) return null;
+    const statePath = path.join(runsLogDir, id, 'state.json');
+    const state = readDurableRunState(statePath);
+    if (!state || state.id !== id || !TERMINAL_RUN_STATUSES.has(state.status)) return null;


Non-blocking follow-up — preserve the request mapping when the daemon dies mid-run. Startup records every durable clientRequestId, but this changed guard refuses to hydrate any saved queued or running state. createOrReuse then receives the mapped id, gets null from hydrateDurableRun, and falls through to create(meta). If the daemon is killed after an AMR run has started but before it writes a terminal state, retrying the same confirmed action after restart therefore creates a new local run and can initiate a second Cloud operation—the exact duplicate this slice is intended to prevent. The new restart test waits for success before stopping the daemon, so it does not exercise this path. Please reconcile persisted non-terminal states on startup while retaining their request-id ownership (for example, materialize them as an interrupted/recovery-required terminal state or safely resume the same run id), and add a restart test that stops with state.json still running, retries the same request, and proves that no second agent/Cloud invocation starts.
_{🔁 Powered by Looper · runner=reviewer · agent=codex · An autonomous AI dev team for your GitHub repos.}

mrcfps · 2026-07-24T17:00:55Z

+    byokProfileId: meta.byokProfileId ?? null,
+    sessionMode: meta.sessionMode ?? null,
+    mediaExecution: meta.mediaExecution ?? null,
+    toolBundle: meta.toolBundle ?? null,


Non-blocking follow-up — fingerprint every execution-affecting request field. runRequestFingerprint hashes this hand-picked subset, but ChatRequest also carries fields that change the generated result or runtime behavior, including systemPrompt, attachments, commentAttachments, context, research, locale, byokMediaDefaults, and titleGeneration. Reusing one clientRequestId with a changed attachment or workspace context currently produces the same fingerprint, so createOrReuse silently returns the old run instead of the documented IDEMPOTENCY_CONFLICT; the tool description explicitly promises that a different payload with the same id is rejected. Please derive the fingerprint from the complete sanitized, normalized execution request (excluding only transport/recovery and analytics-only fields), or maintain an explicit exhaustive typed projection, and extend run-request-idempotency.test.ts with a matrix that changes each execution-affecting field and expects 409 while allowing analytics-only differences.
_{🔁 Powered by Looper · runner=reviewer · agent=codex · An autonomous AI dev team for your GitHub repos.}

open-design-crew · 2026-07-24T17:04:51Z

Scope-correction implementation update (2026-07-25)

The corrected local-runtime implementation is now complete on this PR branch.
The canonical Codex distribution package is also published as
open-design-cloud@open-design 0.3.0:

Completed behavior:

signed packaged Open Design starts headlessly for the local stdio MCP;
interactive collect_brief/confirm_brief card returns readable choices;
narrow Vela browser-login/status tools work without opening the OD GUI;
Vela Cloud, Local Codex, and secure Local BYOK are explicit modes with no
silent fallback;
BYOK sends only a non-secret profile id through MCP/run inputs;
one confirmed action uses one stable request id, including response-loss and
daemon-restart retries;
insufficient balance preserves the original brief/project and resumes the
same logical request after explicit user confirmation;
no remote Open Design MCP, second Cloud runtime, tenant store, or local
billing ledger is present.

Latest local validation:

pnpm guard — passed
pnpm typecheck — passed
daemon changed suites — 12 files / 114 tests passed
packaged changed suites — 2 files / 36 tests passed
web changed suites — 7 files / 321 tests passed
contracts changed suite — 1 file / 7 tests passed
real Vela, Local Codex, and secure BYOK artifact smokes — passed
Plugin Creator + Skill validators — passed
remote clean-Codex-home 0.3.0 install and local MCP registration — passed
unrelated MCP preserved across plugin install/uninstall — passed

Companion Vela validation:

API unit suites — 23 files / 556 tests passed
OAuth E2E — 3 tests passed
go test ./internal/agent -count=1 — passed

Remaining work is release/maintainer-owned: review and merge, production Vela
deployment, signed Open Design release availability, and a production-account
OAuth/top-up acceptance pass. Please do not merge until those checks are
accepted or explicitly waived.

Note: installed odc 0.6.0 advertises PR body editing but its implementation only
accepts label/assignee/reviewer changes, so this audited comment records the
current completion state without falling back to a personal GitHub credential.

open-design-crew Bot requested a review from a team as a code owner July 24, 2026 11:20

lefarcen requested a review from mrcfps July 24, 2026 11:23

lefarcen added needs-validation Runtime change detected; needs human or /explore agent validation. size/XXL PR changes 1500+ lines risk/high High risk: apps/desktop, daemon, auth, migration, workflows, package deps type/feature New feature labels Jul 24, 2026

lefarcen mentioned this pull request Jul 24, 2026

Add a Codex plugin backed by local Open Design and Vela #6054

Open

mrcfps requested changes Jul 24, 2026

View reviewed changes

Comment thread apps/daemon/src/routes/cloud-capabilities.ts Outdated

Comment thread apps/daemon/src/byok/credential-service.ts

Comment thread apps/daemon/src/tools-byok-cli.ts

mrcfps requested changes Jul 24, 2026

View reviewed changes

feat(daemon): expose Vela login through CLI and MCP

cc58e22

mrcfps reviewed Jul 24, 2026

View reviewed changes

feat(mcp): add interactive local brief card

929d29a

mrcfps reviewed Jul 24, 2026

View reviewed changes

feat(packaged): bootstrap local MCP headlessly

bff6662

mrcfps requested changes Jul 24, 2026

View reviewed changes

Cheems added 3 commits July 25, 2026 00:09

feat(daemon): secure local BYOK credential profiles

feadb3f

feat(cli): manage secure BYOK profiles

a6a4de9

feat(web): store BYOK keys in secure profiles

36b751e

mrcfps requested changes Jul 24, 2026

View reviewed changes

fix(runs): deduplicate cloud generation requests

13dc6c5

mrcfps reviewed Jul 24, 2026

View reviewed changes

Uh oh!

Conversation

open-design-crew Bot commented Jul 24, 2026 • edited by itscheems Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Why

What users will see

Surface area

Screenshots

Bug fix verification

Validation

Reviewer guide

Remaining acceptance

Uh oh!

lefarcen commented Jul 24, 2026

Uh oh!

github-actions Bot commented Jul 24, 2026

🚀 Landing page preview

Uh oh!

mrcfps left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Jul 24, 2026

Visual regression review

Capture or diff failures

Uh oh!

mrcfps left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mrcfps left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mrcfps left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mrcfps left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mrcfps left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mrcfps left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

open-design-crew Bot commented Jul 24, 2026

Scope-correction implementation update (2026-07-25)

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

open-design-crew Bot commented Jul 24, 2026 •

edited by itscheems

Loading