JumpStart Workbench Integration

JumpStart Workbench does not call Cosmos services directly the way JumpStart SAP Intelligence or JumpStart AMS do. Instead, it embeds a Cosmos Code binary that itself uses @cosmos/sdk to talk to Cosmos (primarily ADK's V2 WebSocket for agent turns). Integration work for this repo is mostly about correctly staging and resolving that embedded runtime, not about calling Cosmos APIs from the workbench UI.

Required Sibling Layout

Packaged builds require cosmos-code and cosmos-sdk-typescript to be cloned as siblings of cosmos-workbench:

<parent>/
├── cosmos-workbench/         ← this repo (VS Code ext + Electron app + web/mobile)
├── cosmos-code/              ← the opencode fork; Cosmos Code CLI/TUI
├── cosmos-sdk-typescript/    ← @cosmos/sdk, the ADK V2 WebSocket client
└── cosmos-adk-v3/            ← the ADK service (only needed for server-side work)

Two constraints drive this layout:

• @cosmos/sdk is resolved via a file: link, not a registry. cosmos-code/packages/opencode/package.json and cosmos-code/packages/tui/package.json declare "@cosmos/sdk": "file:../../../cosmos-sdk-typescript". Because git+ssh:// fetches are blocked on the corporate network and the package is private, there is no npm/git URL alternative. If cosmos-sdk-typescript is not present as a sibling, bun install in cosmos-code fails. cosmos-sdk-typescript/dist/ is committed, so no SDK build step is required unless you are editing SDK source (see the TypeScript SDK docs).
• JumpStart Workbench stages a locally-built Cosmos Code binary into the VSIX and the desktop app. packages/vscode/scripts/prepare-opencode-cli.mjs and packages/electron/scripts/prepare-opencode-cli.mjs both call scripts/cosmos-runtime.mjs, which looks for the built binary at <parent>/cosmos-code/packages/opencode/dist/opencode-<target>/bin/opencode. Override the location with COSMOS_OPENCODE_ROOT=<absolute path> if cosmos-code lives elsewhere.

Cosmos Provider Seeding

On activation, packages/vscode/src/cosmos-config-seed.ts makes sure the embedded runtime's config has a cosmos provider so there is something to authenticate against immediately:

• If the config file does not exist, it is created from the bundled packages/vscode/resources/cosmos-config/cosmos-code.jsonc (service endpoints and a placeholder model, no secrets).
• If the file exists but has no cosmos provider, the provider is inserted with JSONC edits so existing comments and formatting survive.
• If provider.cosmos.options.workbenchConfigVersion differs from the extension's config migration version, the five service URLs (userServiceURL, configuratorServiceURL, storageServiceURL, adkServiceURL, ragflowServiceURL) on the provider and on every organizations.<name> entry are reset to the bundled defaults, the new version is recorded, and the stored auth token is deleted once. The migration version is a separate constant that changes only when every user must move to new endpoints, so ordinary extension releases do not overwrite customized URLs. All other provider options are preserved.

Sign-in uses OAuth with a public client and PKCE, so no client secret belongs in the config file. Signing in replaces the placeholder provider with one provider per organization, each listing that organization's deployed agents as models.

To move between Cosmos environments without editing the file, use the Switch Environment command (Develop or UAT; Local only for locally built runtimes). See Architecture.

The runtime's live config lives at ~/.config/cosmos-code/cosmos-code.jsonc, not the legacy ~/.config/opencode/opencode.jsonc path; edits to the legacy path silently do nothing once the real config exists.

Pointing At A Locally Modified Runtime

For development, three options exist for running JumpStart Workbench against a modified cosmos-code, in increasing order of fidelity:

1. Source entry via Bun, no build — set OPENCODE_BINARY to a bun run --conditions=browser <path-to-cosmos-code>/packages/opencode/src/index.ts command before running bun run vscode:dev. Cheapest, but the extension expects a single executable path, so argv-splitting issues can occur.
2. Built binary — build cosmos-code (bun run --cwd packages/opencode build) and point OPENCODE_BINARY at the resulting binary.
3. Full stage-and-package — run the packaging scripts so the built binary is staged into resources/opencode-cli exactly as a shipped VSIX or desktop build would use it.

OPENCODE_BINARY/OPENCODE_PATH env vars and the cosmos.opencodeBinary VS Code setting both take priority over the bundled runtime, which is what makes local iteration possible without repackaging.

Shared SAP MCP And SAP Connections

The extension bundles the @cosmos/sap-mcp-server script (synced into packages/vscode/resources/sap-mcp/ by scripts/sync-sap-mcp.mjs during build:extension) and registers it in the runtime config as mcp.sap. The runtime prefixes the server key, so the server's tools appear to agents as sap_* tools. If you define your own mcp.sap entry, the extension leaves it alone.

SAP systems are managed per user with Command Palette commands:

Profiles are stored in ~/.config/cosmos-code/sap-connections.json (overridable with SAP_MCP_CONNECTIONS_FILE). Passwords are kept in VS Code secret storage and reach the runtime only as each profile's passwordEnv environment variable (for example SAP_PW_DEV100); they are never written to disk. Certificate settings support tlsServerName (the certificate host name when the URL uses an IP address or alias, still fully verified), caFile (a PEM CA bundle), and allowUnauthorizedTls (test systems only). Restart the runtime after saving a connection so the SAP tools pick it up.

Related Documentation

• Overview
• Architecture
• Deployment
• TypeScript SDK Quickstart