JumpStart Workbench Architecture

JumpStart Workbench is a monorepo (Bun workspaces) with one shared UI package and several runtime-specific shells, all built on top of a compiled, EY-signed Cosmos Code binary rather than a system-installed OpenCode.

Package Layout

Desktop does not run the web server as a separate sidecar process: packages/electron/main.mjs imports packages/web's server entry point and calls it in-process, then loads the UI from that local server (dev) or from packaged resources/web-dist assets (packaged builds).

Embedded Cosmos Code Runtime

Both the VS Code extension and the desktop app embed a compiled Cosmos Code binary instead of depending on a system opencode install:

1. Build-time staging — scripts/cosmos-runtime.mjs locates the built binary (by default at <parent>/cosmos-code/packages/opencode/dist/opencode-<target>/bin/opencode, overridable with COSMOS_OPENCODE_ROOT) and stages it into packages/vscode/resources/opencode-cli/ and the Electron equivalent, invoked from each package's prepare-opencode-cli.mjs script.
2. Manifest verification — verify-opencode-cli.mjs re-hashes the staged binary against a cosmos-runtime.json manifest, so a packaged VSIX or desktop build can prove what runtime it actually shipped.
3. Runtime resolution order — packages/vscode/src/opencode.ts (resolveOpencodeCliPath) picks the runtime in this order: the cosmos.opencodeBinary VS Code setting → the opencodeBinary value in the shared OpenChamber settings file → the OPENCODE_BINARY, OPENCODE_PATH, OPENCHAMBER_OPENCODE_PATH, or OPENCHAMBER_OPENCODE_BIN environment variables → the bundled runtime → an opencode binary discovered on the machine (~/.cosmos-code/bin, ~/.opencode/bin, package-manager shims, PATH). The bundled runtime outranks anything installed system-wide, which is what makes the extension self-contained. The binary itself is still named opencode; only its on-disk data directories were rebranded to cosmos-code.
4. First-run provider seeding and endpoint migration — on activation, packages/vscode/src/cosmos-config-seed.ts copies the bundled resources/cosmos-config/cosmos-code.jsonc (endpoints only, no secrets) into the runtime's config when no config file exists, or inserts the cosmos provider with JSONC edits when the file exists without one. It then compares provider.cosmos.options.workbenchConfigVersion with the extension's config migration version (COSMOS_CONFIG_MIGRATION_VERSION, not the package version). When they differ, it resets the five Cosmos service URLs (userServiceURL, configuratorServiceURL, storageServiceURL, adkServiceURL, ragflowServiceURL) on the provider and on every organizations.<name> entry, records the new version, and deletes the stored Cosmos auth token once so the next sign-in targets the new environment. Other provider options are preserved.
5. Shared SAP MCP registration — on activation the extension registers the bundled resources/sap-mcp/sap-mcp-server.cjs as the runtime's mcp.sap server, launched by VS Code's own Electron binary in Node mode (ELECTRON_RUN_AS_NODE=1) with short tool names, which the runtime exposes as sap_* tools. The entry is re-pointed on each activation because the extension path changes per version; an mcp.sap entry the user defined themselves is never overwritten.
6. Main-agent-only enforcement — the selected main agent handles all chat work for a session; agent mentions are sent as text rather than delegated. This restriction lives in the embedded Cosmos Code build itself, so an older or externally configured runtime does not automatically inherit it — the workbench must be rebuilt and repackaged against an updated Cosmos Code binary. Existing child-session history is retained regardless.

Deviations From Upstream OpenChamber

JumpStart Workbench renames every identifier VS Code registers in a global, window-wide namespace, because container IDs, view IDs, command IDs, and document-content-provider schemes collide across extensions: the view container (cosmos, contributed to the secondary sidebar), the view (cosmos.chatView), all cosmos.* commands, the cosmos.submenu, the cosmos.* settings namespace, the webview panel types (cosmos.agentManager, cosmos.sessionEditor), and the virtual-diff scheme (cosmos-diff). Without this rename, installing JS Workbench alongside the real OpenChamber extension would leave whichever one registers second without its icon, sidebar, or activation.

Identifiers that are not VS Code registries are deliberately left as upstream (openchamber.*), because renaming them would orphan real user data or break a contract shared with other surfaces: the @openchamber/ui package name, the openchamber:* webview event/message types, the api:openchamber:* bridge routes, the shared ~/.config/openchamber/ settings file (synced with Desktop and Web), the openchamber.settings globalState migration-fallback key, the openchamber.local/openchamber.invalid URL sentinels, the OPENCODE_* environment variables, and the opencode binary name itself. VS Code namespaces globalState/globalStorageUri per extension ID, so those never collided in the first place. Only the runtime's own data directories were rebranded, to cosmos-code.

Branding

VS Code display name JS Workbench, publisher ey-cosmos, package name cosmos-workbench (extension ID ey-cosmos.cosmos-workbench). The extension output channels are named JS Workbench and JS Workbench Runtime. The product family name used in these docs remains JumpStart Workbench.

Cosmos Workspace Binding

Each VS Code workspace is bound to one Cosmos organization and one project. When no binding exists, the extension picks an organization without asking if it can: the currently bound organization, otherwise the single organization named jumpstart (case-insensitive), otherwise the user's only organization. If none of these applies, the user chooses from a picker, and then confirms a project. The Change Organization (cosmos.changeCosmosOrganization) and Change Project (cosmos.changeCosmosProject) commands re-run the selection and start a new session on the new binding. Runtime requests carry x-cosmos-workspace and x-cosmos-context-revision headers that identify the workspace and the binding revision they were issued against; while a binding is being changed, the revision is -1.

Environment Switching

The Switch Environment command (cosmos.switchEnvironment) rewrites the five Cosmos service URLs to the Develop or UAT environment and restarts the runtime, after which the user signs in again. A Local option pointing at the ./manage.sh dev ports (User 8101, Configurator 8100, Storage 8107, ADK 8103, RAGflow 8200) is offered only when the bundled runtime is a locally built, non-published build (its staged version starts with 0.0.0-).

Related Documentation

• Overview
• Integration
• Deployment
• Cosmos Architecture