@kingsoftcloud/ksadk-web 0.3.2 → 0.3.3

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## 0.3.3 - 2026-08-28
+
+### Headless conversation surface
+
+- Add the Node/SSR-safe `@kingsoftcloud/ksadk-web/conversation` entrypoint with
+  strict ConversationSurface/Input/Item v1 decoders, input preflight, bounded
+  HTTP/SSE reconnect, passive renderer data, and the shared identity reducer.
+- Route the bundled Hosted UI through the same conversation client and reducer
+  when a valid Surface is advertised. A Surface HTTP 404 keeps the existing
+  Responses / AG-UI / legacy path; malformed surfaces and server failures do
+  not silently bypass the declared contract.
+- Preserve different item identities even when their text is equal, ignore
+  replayed `(itemId, sourceEventId)` pairs, keep terminal items monotonic, and
+  retain additive unknown item kinds for replay/audit without rendering a
+  repeated transcript card; newer schemas on known kinds safely downgrade to
+  one passive fallback card.
+- Preserve the canonical item timeline for renderers: a separate native tool
+  result enriches its original `callId` tool card rather than rendering a
+  duplicate card, while reasoning, tools and answers keep their original
+  interleaving. Add an immutable exact `kind + payloadSchemaRef` trusted
+  renderer catalog; providers cannot supply executable UI code in event
+  payloads or claim a future schema version.
+- Keep `output` and `reasoning` summaries as a compatibility view beside the
+  canonical timeline, so Studio can adopt the shared reducer without a second
+  text aggregation implementation during the 0.8.3 transition.
+- Keep canonical approvals without a durable `revision` read-only. Consumers
+  must not guess a revision or submit them through the revision-CAS Interaction
+  API until the server supplies an authoritative value.
+- Make attachment upload and model selection first-class canonical inputs in
+  Hosted UI. Unsupported inputs and oversized files fail before upload or turn
+  submission instead of silently degrading to legacy `RunAgent` behavior.
+- Prove the headless entrypoint from a minimal independent consumer across two
+  turns, cursor reconnect, text/tool/approval/unknown-item rendering, and
+  revision-CAS approval submission.
+- Add a repeatable release preflight that runs unit, Node contract, lint, all
+  production builds, canonical Conversation browser E2E, provenance checks,
+  npm packing, and a clean tarball-install public API smoke test.
+
 ## 0.3.2 - 2026-08-21
 
 Release candidate for the durable Interaction/v1 web experience. This is the

package/README.md

@@ -43,6 +43,7 @@ package entrypoints under `dist-lib`.
 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`
@@ -51,6 +52,57 @@ The npm package exposes these stable entrypoints:
 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.
+
+```ts
+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
@@ -89,12 +141,33 @@ Before creating a release or dispatching the workflow, verify the payload:
 
 ```bash
 npm ci
-npm test
-node --test tests/*.test.mjs
-npm run build:all
-npm pack --dry-run --access public
+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:
+
+```bash
+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.

package/RELEASE_PROVENANCE.json

@@ -1,7 +1,7 @@
 {
   "schema_version": 1,
   "package": "@kingsoftcloud/ksadk-web",
-  "version": "0.3.2",
-  "source_commit": "2136448e038b4d8c475fa20e4722252b1ddb2ebc",
+  "version": "0.3.3",
+  "source_commit": "37eb8dd6ae8c44ea4622d39f8c7ae9b13916a793",
   "interaction_contract_digest": "47e1003e03d97abeba232cc3e03a14b9cbcf78b1109870ccd2ce371f073b6211"
 }

package/dist-ksadk/assets/{ArtifactsPanel-DSU1sWD_.js → ArtifactsPanel-CytJCLMc.js}

@@ -1 +1 @@
-import{St as e,Tt as t,bt as n,gt as r,lt as i,n as a,t as o,ut as s,xt as c}from"./index-8ipRcQ-M.js";var l=t(e(),1),u=n();function d(){let e=c(e=>e.visible),t=c(e=>e.content),n=c(e=>e.type),d=c(e=>e.hide),f=(0,l.useRef)(null);if(a(f),!e||!t)return null;let p=o(t);return(0,u.jsxs)(`aside`,{className:i(`flex h-full flex-shrink-0 flex-col border-l border-slate-200/30 bg-white dark:border-slate-800/40 dark:bg-slate-950`,`w-[min(42rem,50vw)]`),children:[(0,u.jsxs)(`div`,{className:`flex h-14 flex-shrink-0 items-center justify-between border-b border-slate-200/30 px-4 dark:border-slate-800/40`,children:[(0,u.jsxs)(`div`,{className:`flex min-w-0 items-center gap-2`,children:[(0,u.jsx)(`span`,{className:`text-sm font-semibold text-slate-900 dark:text-slate-100`,children:`Artifact`}),(0,u.jsx)(`span`,{className:`rounded-md bg-slate-100 px-1.5 py-0.5 font-mono text-[11px] text-slate-500 dark:bg-slate-900 dark:text-slate-400`,children:n})]}),(0,u.jsxs)(`div`,{className:`flex items-center gap-1.5`,children:[(0,u.jsxs)(`button`,{type:`button`,onClick:()=>{let e=new Blob([t],{type:`text/html;charset=utf-8`}),r=URL.createObjectURL(e),i=document.createElement(`a`);i.href=r,i.download=`artifact.${n===`svg`?`svg`:`html`}`,document.body.appendChild(i),i.click(),document.body.removeChild(i),URL.revokeObjectURL(r)},className:`inline-flex items-center gap-1.5 rounded-lg px-2.5 py-1.5 text-xs font-medium text-slate-600 transition hover:bg-slate-100 dark:text-slate-300 dark:hover:bg-slate-900`,title:`Download`,children:[(0,u.jsx)(r,{className:`h-3.5 w-3.5`}),`Download`]}),(0,u.jsx)(`button`,{type:`button`,onClick:d,className:`rounded-lg p-1.5 text-slate-500 transition hover:bg-slate-100 hover:text-slate-900 dark:text-slate-400 dark:hover:bg-slate-900 dark:hover:text-slate-100`,"aria-label":`Close Artifact`,title:`Close`,children:(0,u.jsx)(s,{className:`h-4 w-4`})})]})]}),(0,u.jsx)(`div`,{className:`min-h-0 flex-1`,children:(0,u.jsx)(`iframe`,{ref:f,srcDoc:p,sandbox:`allow-scripts allow-downloads`,title:`Artifact Preview`,className:`h-full w-full border-0 bg-white`})})]})}export{d as ArtifactsPanel};
+import{St as e,Tt as t,bt as n,gt as r,lt as i,n as a,t as o,ut as s,xt as c}from"./index-BkDx9KsG.js";var l=t(e(),1),u=n();function d(){let e=c(e=>e.visible),t=c(e=>e.content),n=c(e=>e.type),d=c(e=>e.hide),f=(0,l.useRef)(null);if(a(f),!e||!t)return null;let p=o(t);return(0,u.jsxs)(`aside`,{className:i(`flex h-full flex-shrink-0 flex-col border-l border-slate-200/30 bg-white dark:border-slate-800/40 dark:bg-slate-950`,`w-[min(42rem,50vw)]`),children:[(0,u.jsxs)(`div`,{className:`flex h-14 flex-shrink-0 items-center justify-between border-b border-slate-200/30 px-4 dark:border-slate-800/40`,children:[(0,u.jsxs)(`div`,{className:`flex min-w-0 items-center gap-2`,children:[(0,u.jsx)(`span`,{className:`text-sm font-semibold text-slate-900 dark:text-slate-100`,children:`Artifact`}),(0,u.jsx)(`span`,{className:`rounded-md bg-slate-100 px-1.5 py-0.5 font-mono text-[11px] text-slate-500 dark:bg-slate-900 dark:text-slate-400`,children:n})]}),(0,u.jsxs)(`div`,{className:`flex items-center gap-1.5`,children:[(0,u.jsxs)(`button`,{type:`button`,onClick:()=>{let e=new Blob([t],{type:`text/html;charset=utf-8`}),r=URL.createObjectURL(e),i=document.createElement(`a`);i.href=r,i.download=`artifact.${n===`svg`?`svg`:`html`}`,document.body.appendChild(i),i.click(),document.body.removeChild(i),URL.revokeObjectURL(r)},className:`inline-flex items-center gap-1.5 rounded-lg px-2.5 py-1.5 text-xs font-medium text-slate-600 transition hover:bg-slate-100 dark:text-slate-300 dark:hover:bg-slate-900`,title:`Download`,children:[(0,u.jsx)(r,{className:`h-3.5 w-3.5`}),`Download`]}),(0,u.jsx)(`button`,{type:`button`,onClick:d,className:`rounded-lg p-1.5 text-slate-500 transition hover:bg-slate-100 hover:text-slate-900 dark:text-slate-400 dark:hover:bg-slate-900 dark:hover:text-slate-100`,"aria-label":`Close Artifact`,title:`Close`,children:(0,u.jsx)(s,{className:`h-4 w-4`})})]})]}),(0,u.jsx)(`div`,{className:`min-h-0 flex-1`,children:(0,u.jsx)(`iframe`,{ref:f,srcDoc:p,sandbox:`allow-scripts allow-downloads`,title:`Artifact Preview`,className:`h-full w-full border-0 bg-white`})})]})}export{d as ArtifactsPanel};