KSADK Web

KSADK Web is the shared Web UI source for AgentEngine hosted UI and the KSADK embedded static UI.

Consumers

• kingsoftcloud/ksadk-python consumes @kingsoftcloud/ksadk-web@latest by default and copies dist-ksadk into ksadk/server/static.
• agentengine-hosted-ui consumes @kingsoftcloud/ksadk-web@latest by default and keeps private deployment shell files such as Docker, nginx, Helm, image tags, and runtime environment injection outside this repository.

Public Demo

The GitHub Pages demo is published from the reviewed build:ksadk output:

https://kingsoftcloud.github.io/ksadk-web/

Development

npm ci
npm run dev
npm test

Builds

npm run build:ksadk
npm run build:hosted
npm run build:lib
npm run build:all

build:ksadk uses relative assets for the SDK embedded UI. build:hosted uses the /chat/ base path for the hosted UI bundle. build:lib emits the package entrypoints under dist-lib.

Package Exports

The npm package exposes these stable entrypoints:

• @kingsoftcloud/ksadk-web/components
• @kingsoftcloud/ksadk-web/conversation (headless, Node/SSR-safe)
• @kingsoftcloud/ksadk-web/runtime
• @kingsoftcloud/ksadk-web/capabilities
• @kingsoftcloud/ksadk-web/styles
• @kingsoftcloud/ksadk-web/types

Hosted UI should import the shared shell from the package and keep private auth, routing, feature flags, Docker, nginx, and Helm logic in its own repo.

Headless conversation client

@kingsoftcloud/ksadk-web/conversation provides strict ConversationSurface/Input/Item decoders, the identity reducer, passive renderer data, and a small HTTP/SSE reference client. It has no React or DOM runtime dependency and can be imported by Node/SSR applications.

import {
  HttpConversationClient,
  buildConversationInput,
} from '@kingsoftcloud/ksadk-web/conversation'

const client = new HttpConversationClient()
const bootstrap = await client.getSurface('agent-id', 'session-id')
const result = await client.streamTurn({
  bootstrap,
  input: buildConversationInput({
    inputId: 'input-id',
    sessionId: 'session-id',
    idempotencyKey: 'turn-id',
    parts: [{ kind: 'text', text: 'Hello' }],
  }),
  onUpdate(snapshot) {
    // Render snapshot.presentation. It is already reduced by canonical item
    // identity and is safe to replace after a reconnect or replay.
    renderConversation(snapshot.presentation)
  },
})

The client submits a turn once and only reconnects through the canonical Run event endpoint. onUpdate and the final result use the same reducer: equal text from different item identities is retained, replayed (itemId, sourceEventId) pairs are idempotent, and a terminal item never regresses. It does not accept tokens, cookies, credential modes, or provider-specific request fields; applications keep authentication at their same-origin server boundary or in an injected transport.

The bundled Hosted UI uses this same client and reducer when the server returns a valid ConversationSurface. HTTP 404 is the compatibility signal for the existing Responses / AG-UI / legacy path. A declared but invalid or unavailable surface fails closed, and unknown item kinds or schema versions render as passive fallback cards rather than provider-specific UI.

Approval and structured-input items are actionable only when their canonical payload carries the server's durable, non-negative revision. Without that value the shared Hosted UI intentionally renders the item read-only: it never guesses revision 0 or bypasses the Interaction API's revision-CAS contract. Likewise, unknown payloads and unsafe artifact URIs remain passive content.

Release Contract

Consumers should record the resolved KSADK Web package version and lockfile integrity they build from. KSADK release notes must mention the KSADK Web release used to generate ksadk/server/static.

Npm releases are published by GitHub Actions using npm Trusted Publishing. The workflow is .github/workflows/publish-npm.yml and is triggered by a published GitHub Release or manual workflow_dispatch. Do not store npm tokens in repository secrets for the normal release path.

GitHub Release notes are entered manually and must use normal Markdown, not a JSON-style escaped string. Do not paste text containing literal \n sequences into the release body. Follow the existing v0.2.10 / v0.2.11 structure:

## What's New

- **Area name**: User-facing behavior change.
- **Area name**: User-facing behavior change.

## Full Changelog
https://github.com/kingsoftcloud/ksadk-web/compare/<previous-tag>...<new-tag>

Release notes should stay concise and product-facing:

• Use ## What's New and ## Full Changelog.
• Prefer short bullets that describe shipped behavior, not CI narration.
• Put verification details in the PR, workflow run, or changelog review notes, not in the GitHub Release body.
• Keep the release title in the form ksadk-web vX.Y.Z.

Before creating a release or dispatching the workflow, verify the payload:

npm ci
npx playwright install chromium
npm run release:preflight

The preflight is intentionally stricter than a development build: it requires a clean worktree, checks the frozen Git source recorded in RELEASE_PROVENANCE.json, rejects content changes under an already tagged version, runs the canonical Conversation browser flow, creates the real npm tarball, installs it into a disposable consumer, and imports the public @kingsoftcloud/ksadk-web/conversation API. During development only, use npm run release:preflight -- --allow-unreleased --allow-dirty to rehearse the same tests without claiming the current commit is a releasable source.

After the next version is set and all code is committed, freeze its provenance from that clean commit before the final attestation commit:

npm run release:provenance -- generate
git add RELEASE_PROVENANCE.json
git commit -m "chore(release): attest ksadk-web source"
npm run release:preflight

The generator refuses dirty worktrees and versions whose vX.Y.Z tag already exists. Never edit source_commit by hand or regenerate provenance for an already published version.

The publish workflow checks whether package.json's exact version is already present on npm. Existing versions are skipped because npm packages are immutable; publish a new patch version for any package-content change.

Hosted UI and KSADK static sync consume the latest released @kingsoftcloud/ksadk-web package by default. Release builds should record the resolved package version and lockfile integrity; set an explicit version only when rollback or release-freeze requires it.