feat(bridle): "New chat" archives the transcript instead of clearing locally (v0.13.3)

Closes the loop on the New chat UX. Before: local chat cleared but
the server-side transcript was untouched, and the next reload would
restore it (token-flow) — fixed in v0.13.2 by suppressing the next
replay, but the history just kept piling up on the server with no
way to roll it over.

Now the SDK calls POST /api/agent/<id>/transcript/archive?channel=<...>
right before the reconnect. Two implementations, hub-side:

1. Bridle hub (bridle/nestjs/): new
   IBridleTranscriptGateway.archive() with a default that falls back
   to delete(). Integrators override to do the "right thing" for their
   storage (rename to timestamped sibling, move to cold tier, etc.).
   Controller endpoint POST :agentId/transcript/archive returns
   { archivedPath? }.

2. Ranch hub (ranch/api/src/slices/bridle/): the controller reads
   data/sessions/bridle:<channel>.jsonl, writes the same content to
   data/sessions/bridle:<channel>.<iso-ts>.archived.jsonl, then
   deletes the live file. No-op when the live file is empty/missing.
   Admins still have full history under the .archived. files; the
   visitor gets a clean slate.

SDK side: archive call is best-effort. If the endpoint isn't there
(older hub) or the request fails, we still clear locally and reconnect
— the existing skipNextTranscript flag keeps the replay from undoing
the clear. Net effect: New chat is consistent regardless of which hub
version the embed is talking to.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: dmitriyzhuk

nestjs/bridle.controller.ts

@@ -137,4 +137,26 @@ export class BridleController {
       this.logger.warn(`Transcript reset failed for ${agentId}/${channel}: ${(err as Error).message}`)
     }
   }
+
+  @ApiOperation({
+    description:
+      'Archive the persisted chat transcript for an agent/channel. Used by the embed\'s "New chat" action when the integrator wants the visitor to see a clean slate but still keep the prior conversation for admin/audit. Default integrator binding falls back to delete; override IBridleTranscriptGateway.archive() to move-with-timestamp instead.',
+    operationId: 'archiveBridleTranscript',
+  })
+  @ApiQuery({ name: 'channel', required: false, description: 'Session channel — defaults to "admin".' })
+  @FlatResponse()
+  @Post(':agentId/transcript/archive')
+  @HttpCode(200)
+  async archiveTranscript(
+    @Param('agentId') agentId: string,
+    @Query('channel') channelRaw?: string,
+  ): Promise<{ archivedPath?: string }> {
+    const channel = (channelRaw ?? 'admin').trim() || 'admin'
+    try {
+      return await this.transcripts.archive(agentId, channel)
+    } catch (err) {
+      this.logger.warn(`Transcript archive failed for ${agentId}/${channel}: ${(err as Error).message}`)
+      return {}
+    }
+  }
 }

nestjs/domain/bridleTranscript.gateway.ts

@@ -37,4 +37,22 @@ export abstract class IBridleTranscriptGateway {
    * succeed when nothing exists.
    */
   abstract delete(agentId: string, channel: string): Promise<void>
+
+  /**
+   * Move the transcript for `(agentId, channel)` aside so subsequent
+   * `read()` calls return an empty list, without losing the data — used
+   * by the embed's "New chat" action when the visitor wants a fresh
+   * conversation but the integrator wants to keep the history for
+   * admin/audit. Implementations typically rename the live file with
+   * a timestamp suffix (e.g. `bridle:<channel>.<iso-ts>.archived.jsonl`)
+   * and return that path. Returning `{}` is fine when nothing was
+   * there to archive in the first place.
+   *
+   * Default implementation falls back to `delete()` — integrators can
+   * upgrade by overriding this method.
+   */
+  async archive(agentId: string, channel: string): Promise<{ archivedPath?: string }> {
+    await this.delete(agentId, channel)
+    return {}
+  }
 }

sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleanslice/bridle",
-  "version": "0.13.2",
+  "version": "0.13.3",
   "description": "Embeddable web chat for Bridle — drop-in <script> or programmatic init.",
   "type": "module",
   "main": "./dist/bridle.mjs",

sdk/src/BridleChat.ce.vue

@@ -787,6 +787,28 @@ function toggleMenu(): void {
  */
 async function startNewChat(): Promise<void> {
   menuOpen.value = false
+  // Ask the hub to archive the current transcript before we reconnect —
+  // best-effort: if the endpoint isn't there (older hub) or the request
+  // fails, we still clear locally so the visitor's UI is consistent.
+  // Server-side hubs that don't override IBridleTranscriptGateway.archive
+  // fall back to delete(); Ranch's controller moves the live JSONL to a
+  // timestamped sibling so admins still have the conversation.
+  const channel = client?.getClientId?.()
+  if (channel && props.apiUrl && props.agentId) {
+    try {
+      const url =
+        `${props.apiUrl.replace(/\/$/, '')}` +
+        `/api/agent/${encodeURIComponent(props.agentId)}/transcript/archive` +
+        `?channel=${encodeURIComponent(channel)}`
+      const headers: Record<string, string> = {}
+      if (typeof props.token === 'string' && props.token) {
+        headers.Authorization = `Bearer ${props.token}`
+      }
+      await fetch(url, { method: 'POST', headers })
+    } catch (err) {
+      console.warn('[bridle] transcript archive failed (continuing):', err)
+    }
+  }
   if (typeof window !== 'undefined') {
     try {
       window.localStorage.removeItem(`bridle:anon:${props.agentId}`)
@@ -801,11 +823,9 @@ async function startNewChat(): Promise<void> {
   greetingShown.value = false
   isTyping.value = false
   connectionError.value = null
-  // Tell the next welcome handler to skip its transcript replay. Server-
-  // side history isn't purged (no hub endpoint for that), but suppressing
-  // the replay is what the user actually wanted from "New chat" — a
-  // visibly fresh conversation. Continuity on subsequent reloads is
-  // preserved unless they hit New chat again.
+  // Suppress the next transcript replay too — belt-and-braces in case the
+  // archive endpoint was a no-op (older hub without the override) and the
+  // live transcript wasn't actually moved.
   skipNextTranscript = true
   if (props.apiUrl && props.agentId) {
     await connect()