JumpStart Integration Guide

JumpStart integrates with Cosmos through @cosmos/sdk. New generic platform behavior should go into cosmos-sdk-typescript; JumpStart should keep only application concerns: Next.js routes, Prisma models, project access policy, blueprints, connector credentials, and SAP/Oracle/BTP domain tools.

Current Integration Notes

• JumpStart passes the execution context (including the manifest hash), runtime skill and KB selections, and the canonical project ID through the SDK. It sends no compaction or history-filter controls; ADK owns them.
• Configurator runtime manifest calls use on-behalf-of headers, and dry-run diagnostics surface blocking manifest errors before execution.
• Project members, groups, and journey grants are read from and written to native Cosmos project RBAC; there are no local mirror tables.
• DMS uploads use a single async direct-to-cloud upload path through SDK upload sessions, with a 6 GB size cap enforced by Storage.
• Compass document write tools, workbench delete tools, and built-in tools run through the app-local tool boundary.

SDK Setup

JumpStart installs the TypeScript SDK from the Cosmos SDK repository. Use the current package.json pin when documenting or debugging a deployed branch; do not copy older commit pins from stale docs.

{
  "@cosmos/sdk": "github:ey-org/cosmos-sdk-typescript#<current-pin>"
}

A request-scoped CosmosClient is created server-side from the current NextAuth session (or, for worker tool calls, from the bearer token the worker passes). Token refresh is owned by NextAuth, while the SDK receives the current Cosmos access token, service URLs, and the canonical project ID.

import { CosmosClient, decodeCosmosAccessToken } from "@cosmos/sdk";
import { COSMOS_ORG_ID } from "@/lib/config";

export function createCosmosClient(accessToken: string, projectId?: string) {
  const decoded = decodeCosmosAccessToken(accessToken);

  return new CosmosClient({
    orgId: COSMOS_ORG_ID,
    ...(projectId ? { projectId } : {}), // canonical Cosmos project UUID
    userId: decoded.user_id,
    services: {
      user: process.env.COSMOS_USER_SERVICE_URL,
      chat: process.env.COSMOS_CHAT_SERVICE_URL,
      configurator: process.env.COSMOS_CONFIGURATOR_SERVICE_URL,
      tools: process.env.COSMOS_TOOLS_SERVICE_URL,
      observer: process.env.COSMOS_OBSERVER_SERVICE_URL,
      storage: process.env.COSMOS_STORAGE_SERVICE_URL,
      adk: process.env.COSMOS_ADK_SERVICE_URL,
      ragflow: process.env.COSMOS_RAGFLOW_SERVICE_URL,
    },
    // Optional fallback for services without a direct URL
    gatewayUrl: process.env.COSMOS_GATEWAY_URL,
    authManager: {
      tokens: {
        accessToken,
        refreshToken: "",
        expiresAt: new Date(decoded.exp * 1000),
      },
    },
  });
}

Only services with a configured URL are passed in services. For session-backed clients, JumpStart replaces the SDK refresh with a re-read of the current NextAuth session tokens, so NextAuth remains the only owner of refresh-token rotation.

Authentication

JumpStart uses two auth modes:

User Authentication (NextAuth + OAuth2 PKCE)

Service Authentication (client_credentials)

JumpStart also authenticates as a service for server-to-server calls that don't need a user context (project API queries, delegated user onboarding, storage ACL management). This uses the SDK's acquireServiceToken() with a multi-audience token cache.

Configurator calls made on a user's behalf send the service token plus X-On-Behalf-Of-User-Id and X-Project-Id; the user's own token is not forwarded. See SDK Service Auth for the SDK reference and Authentication for the platform token model.

Durable Chat Jobs

The primary AI flow uses job endpoints and a worker process.

Jobs are queued with BullMQ on Redis and processed by the worker.

ADK V2 Pattern

const result = await cosmos.sendMessageViaADK(sessionId, userMessage, {
  systemPrompt,
  providerId,
  modelId,
  skills,
  excludeTools,
  additionalCollectionIds,
  executionContext,       // app/scope boundary, including manifestHash
  observabilityMetadata,
  channel: "jumpstart",
  appName,
  maxToolRoundtrips,
  onChunk: (text) => appendJobChunk(jobId, text),
  onToolCallArgsDelta: (name, path, delta) => recordToolArgs(jobId, name, path, delta),
  onToolStart: (name) => markToolStarted(jobId, name),
  onToolComplete: (name, output) => markToolComplete(jobId, name, output),
  onCustomEvent: (type, payload) => recordCustomEvent(jobId, type, payload),
  onUsage: (usage) => recordContextUsage(jobId, usage),
  onError: (code, message, fatal) => markJobError(jobId, code, message, fatal),
});

When a JumpStart tool handler returns { ok: false, error } or throws, the SDK sends the error message as the tool result's error, so the model sees the actual failure reason. Use prompt-only mode for BBP/workbench chat unless a flow explicitly needs a saved Cosmos agent. The COSMOS_AGENT_ID environment variable is for the ABAP AI Fix flow, not the general BBP generation path.

Storage And DMS

JumpStart uses Cosmos Storage for uploaded documents, previews, and generated files. Route handlers should call SDK storage helpers rather than duplicating Storage API behavior.

Connector Tools

JumpStart connector tools run locally inside the worker. They are not deployed to Cosmos MCP.

The SAP data explorer blocks sensitive tables and uses a circuit breaker for failing SAP calls.

Keep credentials inside JumpStart's encrypted connection records. Tool handlers should receive only the scoped project/connection context they need.

Project Access

Native Cosmos project RBAC is the only store for project members, groups, and app-surface (journey) grants. JumpStart reads and writes them through the User Service project APIs.

Knowledge Map

app/api/cosmos/knowledge-map/graphs and graphs/[id] serve the Knowledge Map. JumpStart calls Configurator with its service token, the signed-in user as on-behalf-of subject, and the canonical project ID. A graph is returned only when the journey agent's manifest grants graph.read on it, the graph is ready, and the project catalog grants it. Access is checked again on every read.

Cost Limits

app/api/cosmos/my-cost-limits returns the signed-in user's effective session, weekly, and monthly limits from the SDK costLimits.getMyCostLimits(). Limit-increase requests use app/api/cosmos/limit-increase-requests; the server snapshots the current limits, so JumpStart sends only the requested values.

API Route Ownership

Test Expectations

Run unit tests for ordinary route/tool changes. Use opt-in Playwright suites only when touching the relevant live surfaces:

Related Documentation

• Architecture
• Deployment
• TypeScript SDK Quick Start
• ADK V2 Streaming