@kingsoftcloud/ksadk-web 0.3.1 → 0.3.3

package/CHANGELOG.md

@@ -1,5 +1,150 @@
 # 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
+reviewed source that replaces the internal beta sequence. Publication remains
+blocked on the current-digest cross-repository preproduction gate and uses the
+protected release workflow only after that gate is green.
+
+- Unify the Hosted UI composer with Studio's compact attachment, approval,
+  model, Goal, and Plan controls. The runtime's ordinary agent loop remains
+  internal rather than appearing as a third user-selectable mode; a future
+  eval-driven improvement loop must advertise its own honest capability.
+- Simplify the session list: completed runs no longer expose raw status text;
+  active sessions use a small activity ring and subtle background, while failed
+  sessions use a restrained error dot.
+- Keep RuntimeCapabilityMatrix decoding executable before the TypeScript build,
+  so the same fail-closed contract projection is covered by both browser tests
+  and the npm publication workflow's Node compatibility gate.
+
+## 0.3.2-beta.5 - 2026-08-21
+
+When the composer Interaction tray owns a pending approval, its tool-history
+row is now strictly read-only. This removes the second legacy approve/reject
+entry point while preserving the command arguments and terminal audit result.
+
+## 0.3.2-beta.4 - 2026-08-21
+
+Fixes the legacy Responses approval bridge: a pending approval is retained in
+the read-only tool history and also normalized into the unified Interaction
+tray immediately above the composer.  The submit still uses the compatible
+Responses approval transport when Interaction/v1 is unavailable.
+
+## 0.3.2-beta.3 - 2026-08-20
+
+Adds package-internal release provenance. Hosted UI and the preproduction gate
+can verify the resolved tarball's source basis and Interaction/v1 contract
+digest instead of trusting an external evidence label.
+
+## 0.3.2-beta.2 - 2026-08-20
+
+Rebuilt the immutable beta artifact from the complete Interaction/v1 source.
+This supersedes `0.3.2-beta.1`, whose vendored Hosted UI tarball predated the
+two fixes below.
+
+- Treat a successful `SubmitInteraction` receipt as durable acceptance, not as
+  proof that the framework execution has already completed its resolution.
+- Add the queue tray and read-only historical interaction anchors to the
+  published artifact, rather than leaving them only on the Web source branch.
+
+## 0.3.2-beta.1 - 2026-08-19
+
+> Unifies durable human-in-the-loop decisions behind one `Interaction/v1`
+> client. Counterpart of the agent-kernel Interaction/v1 contract: pending
+> approvals, structured inputs, and AG-UI interrupts normalize to a single
+> Interaction shape with one submit path (`SubmitInteraction`) with
+> revision CAS, idempotency keys, and first-wins terminal semantics.
+
+### Interaction/v1 (headless core)
+
+- New `src/core/interaction/` module: `InteractionClientImpl` + shared
+  `InteractionStore` with strict first-wins semantics (a terminal record
+  never regresses to pending), revision-based optimistic concurrency, and
+  an idempotency-key double-submit guard.
+- Transport adapters normalize three sources into the same Interaction:
+  Interaction/v1 SessionEvents (`interaction.requested` / `.resolved`,
+  rejection is `resolved.outcome="rejected"`, not a fifth event type),
+  Responses `mcp_approval_request`, and AG-UI interrupts. Components never
+  branch on the approval protocol.
+- New public API: `POST /agentengine/api/v1/SubmitInteraction`
+  (`submitInteraction` on `ApiFacade`), receipt decoded with the canonical
+  agent-kernel/v1 strict decoder. Pure `/v1/responses` clients keep the
+  official `mcp_approval_response` path.
+- Refresh/replay: session load replays recent durable SessionEvents into
+  the store so a pending Interaction is restored without creating a second
+  request; a double click, a stale tab, or a replayed history can never
+  duplicate a decision.
+
+### UI
+
+- `InteractionTray` renders above the composer with the current pending
+  item, pending count, and queue navigation; the composer input is
+  visually subordinated while a decision is pending.
+- `InteractionHistoryAnchor` replaces interactive historical approval
+  buttons with a read-only status retaining actor, decision time,
+  outcome, and a redacted response summary.
+- A2UI production wire locked to `0.9.1` with catalog digest validation
+  (`validateA2uiPresentation`). Unknown wire versions or catalog
+  mismatches fall back to the canonical JSON schema form, then to plain
+  approve/reject controls. A validation failure is never mapped to an
+  approval.
+- Expiry: interactions with a past `expires_at` disable submission
+  client-side and surface an expired notice.
+
+### Compatibility
+
+- Old servers without the `interaction_v1` capability keep the 0.3.1
+  Responses (`mcp_approval_response`) and AG-UI (`resumeAguiInterrupt`)
+  callbacks; the fallback is isolated in the adapters and the shared UI is
+  unchanged.
+- Public runtime bundle exports `InteractionClientImpl`, `Interaction`,
+  adapters, and `interactionIdempotencyKey`.
+
+### Supply chain
+
+- Refresh the lockfile's production transitive dependencies for the `0.3.2`
+  candidate: Mermaid/DOMPurify and PostCSS/nanoid now resolve to the patched
+  releases verified by `npm audit --omit=dev`.
+
 ## 0.3.1 - 2026-08-12
 
 > Identity-aware runtime item reducer. Counterpart of the KsADK `0.8.1`
@@ -28,11 +173,10 @@
   identity-aware version. `0.3.0` used the v1 heuristic reducer and will
   duplicate or drop output when paired with canonical v2 producers.
 
-## 0.3.0 - 2026-07-24
+## 0.3.0 - 2026-07-29
 
-> **Review candidate, not a published npm release.** `0.3.0` is the web
-> counterpart of the KsADK `0.8.0` review branch. No npm tag or package is
-> created by this changelog entry.
+> Published baseline for Hosted runtime transport and the KsADK `0.8.0`
+> web integration.
 
 ### Hosted runtime transport
 

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

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

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

@@ -1 +1 @@
-import{bt as e,ht as t,lt as n,n as r,t as i,ut as a,wt as o,xt as s,yt as c}from"./index-R52pJJvg.js";var l=o(s(),1),u=c();function d(){let o=e(e=>e.visible),s=e(e=>e.content),c=e(e=>e.type),d=e(e=>e.hide),f=(0,l.useRef)(null);if(r(f),!o||!s)return null;let p=i(s);return(0,u.jsxs)(`aside`,{className:n(`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:c})]}),(0,u.jsxs)(`div`,{className:`flex items-center gap-1.5`,children:[(0,u.jsxs)(`button`,{type:`button`,onClick:()=>{let e=new Blob([s],{type:`text/html;charset=utf-8`}),t=URL.createObjectURL(e),n=document.createElement(`a`);n.href=t,n.download=`artifact.${c===`svg`?`svg`:`html`}`,document.body.appendChild(n),n.click(),document.body.removeChild(n),URL.revokeObjectURL(t)},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)(t,{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)(a,{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};