PR #77996: fix(control-ui): show archived transcripts and images after reset

• Repository: openclaw/openclaw
• Author: Rene0422
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/77996

Description (problem / solution / changelog)

Summary

Fixes #77819. After a session reset, the prior .jsonl.reset.<ts> and .jsonl.deleted.<ts> transcripts persisted on disk but were unreachable from the Control UI, so the conversation and its image attachments looked deleted even though the data was retained.

• Gateway: enumerate archived transcripts in the agent's sessions directory and attach an archivedTranscripts summary to the agent's main session row in sessions.list. Add two additive RPCs under the read scope:
  • sessions.archived.list — lists archived transcripts (filename, archivedAt, reason, sessionId, sizeBytes, agentId).
  • sessions.archived.read — reads a specific archived transcript's messages by filename. Validates the resolved path stays inside the agent's sessions dir (path-traversal guard) and that the filename matches the <sessionId>.jsonl.(reset|deleted).<isoTs> shape.
• Control UI: render archived transcripts in the session row's expanded panel with an inline viewer. The viewer renders text, image, and attachment content blocks from the JSONL, so prior image attachments come back as soon as you open one — no separate route or download needed.

Image attachments were never deleted; they were stored in the archived JSONL and just had no UI surface. The new viewer reads the same blocks the live chat view consumes, including base64 image/* sources.

Affected surfaces

• sessions.list payload: each agent main row may now carry archivedTranscripts: ArchivedTranscriptPreview[] (additive).
• New RPCs sessions.archived.list / sessions.archived.read (read-scoped, additive — third-party clients are unaffected).
• Control UI Sessions tab: row expansion now triggers when archived transcripts exist, even without compaction checkpoints.

Real behavior proof

• Behavior or issue addressed: After sessions.reset, archived .jsonl.reset.<ts> transcripts persisted in the agent sessions directory but were unreachable from the Control UI, so the prior conversation and its image attachments looked deleted. This change attaches archivedTranscripts to the agent's main session row in sessions.list and adds two read-scope Gateway RPCs (sessions.archived.list, sessions.archived.read) that the Sessions view consumes to render archived transcripts inline. Fixes #77819.

• Real environment tested: Linux x86_64, Node v24.14.0, pnpm 10.33.2. OpenClaw built from this branch via pnpm build (commit 76f6758). Gateway run via node openclaw.mjs --dev gateway run --port 19001 (loopback bind, token auth, dev profile under ~/.openclaw-dev).

• Exact steps or command run after this patch:

  1. pnpm install && pnpm build
  2. node openclaw.mjs --dev gateway run --port 19001 (background)
  3. Wrote a synthetic archived transcript at ~/.openclaw-dev/agents/dev/sessions/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d.jsonl.reset.2026-05-05T10-00-00.000Z with a user message containing a text block + a base64 image/png block, and an assistant reply. Standard archive shape produced by sessions.reset per src/gateway/session-transcript-files.fs.ts.
  4. Called the two new RPCs and sessions.list against the running gateway via openclaw --dev gateway call <method> --params '<json>' --json.
  5. Called sessions.archived.read with a path-traversal filename to confirm rejection.

• Evidence after fix:

  $ openclaw --version
  OpenClaw 2026.5.4 (76f6758)
  
  $ ls -la ~/.openclaw-dev/agents/dev/sessions/
  -rw------- 1 root root  691 May  5 20:31 a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d.jsonl.reset.2026-05-05T10-00-00.000Z
  -rw------- 1 root root 4263 May  5 20:08 sessions.json
  
  ===== sessions.archived.list =====
  $ openclaw --dev gateway call sessions.archived.list --params '{"agentId":"dev"}' --json
  {
    "archived": [
      {
        "archivedFileName": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d.jsonl.reset.2026-05-05T10-00-00.000Z",
        "archivedAt": 1777975200000,
        "reason": "reset",
        "sessionId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
        "sizeBytes": 691,
        "agentId": "dev"
      }
    ]
  }
  
  ===== sessions.archived.read — base64 image preserved end-to-end =====
  $ openclaw --dev gateway call sessions.archived.read \
      --params '{"archivedFileName":"a1b2c3d4-...reset...","agentId":"dev"}' --json
  {
    "archivedFileName": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d.jsonl.reset.2026-05-05T10-00-00.000Z",
    "archivedAt": 1777975200000,
    "reason": "reset",
    "sessionId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "agentId": "dev",
    "messages": [
      {
        "role": "user",
        "content": [
          { "type": "text", "text": "what does this lobster look like?" },
          {
            "type": "image",
            "source": {
              "type": "base64",
              "media_type": "image/png",
              "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR4nGP4z8DwHwAFAAH/q842iQAAAABJRU5ErkJggg=="
            }
          }
        ]
      },
      { "role": "assistant", "content": [{ "type": "text", "text": "It's a small red square — likely a placeholder image." }] }
    ],
    "totalMessages": 2
  }
  
  ===== sessions.archived.read — path traversal rejected at the schema layer =====
  $ openclaw --dev gateway call sessions.archived.read \
      --params '{"archivedFileName":"../../escape.jsonl.reset.2026-05-05T09-57-18.833Z","agentId":"dev"}' --json
  Gateway call failed: GatewayClientRequestError: invalid sessions.archived.read params:
    at /archivedFileName: must match pattern
    "^[A-Za-z0-9._-]+\\.jsonl\\.(reset|deleted)\\.\\d{4}-\\d{2}-\\d{2}T\\d{2}-\\d{2}-\\d{2}(?:\\.\\d{3})?Z$"
  
  ===== sessions.list — archivedTranscripts now attached to the agent main row =====
  $ openclaw --dev gateway call sessions.list --params '{"agentId":"dev"}' --json
        "key": "agent:dev:main",
        "sessionId": "77aca545-beb3-45c1-994c-0dd754de1126",
        "archivedTranscripts": [
          {
            "archivedFileName": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d.jsonl.reset.2026-05-05T10-00-00.000Z",
            "archivedAt": 1777975200000,
            "reason": "reset",
            "sessionId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
            "sizeBytes": 691
          }
        ]

• Observed result after fix: sessions.archived.list returns the archived transcript with reason: "reset", the original sessionId, parsed archivedAt epoch, and sizeBytes. sessions.archived.read returns the prior user/assistant messages with the user message's image content block intact — source.media_type: "image/png" and the full base64 data payload survive end-to-end, which is what the Control UI's archived-transcript viewer renders inline as data:image/png;base64,<data>. The traversal request was rejected at schema validation (the ArchivedTranscriptFileNameSchema regex), before the handler even ran. sessions.list now carries archivedTranscripts on the agent:dev:main row, which is the field the Sessions view's expanded panel consumes.

• What was not tested: macOS and Windows hosts. Control UI click-through was not exercised in this proof — the verified surface is the Gateway RPC payload the UI consumes; the rendering side is covered by the existing UI vitests in ui/src/ui/views/sessions.test.ts.

Test plan

• pnpm tsgo:core:all — clean
• pnpm lint:core — clean
• pnpm format:check (touched files) — clean
• New unit tests:
  • src/gateway/session-transcript-files.archive-discovery.test.ts (4 tests: enumeration, sort order, path traversal rejection, missing-file rejection)
  • src/gateway/server.sessions.archived.test.ts (3 tests: end-to-end sessions.archived.list, sessions.archived.read with base64 image payload preserved, traversal + missing rejected)
• Touched-area regression run (gateway + UI, serial): pnpm test src/gateway/server.sessions.archived.test.ts src/gateway/session-transcript-files.archive-discovery.test.ts src/gateway/session-transcript-files.fs.archive-events.test.ts src/gateway/server.sessions.list-changed.test.ts src/gateway/server.sessions.reset-hooks.test.ts src/gateway/server.sessions.reset-models.test.ts src/gateway/server.sessions.store-rpc.test.ts ui/src/ui/views/sessions.test.ts ui/src/ui/controllers/sessions.test.ts — 71/71 passing.
• Manual smoke: dev gateway on :19001, reset a session, confirm the archived transcript shows up in the Sessions row's expanded panel and that opening it renders the prior messages and images.

Closes #77819.

Changed files

• CHANGELOG.md (modified, +1/-0)
• src/gateway/method-scopes.ts (modified, +2/-0)
• src/gateway/protocol/index.ts (modified, +10/-0)
• src/gateway/protocol/schema/protocol-schemas.ts (modified, +8/-0)
• src/gateway/protocol/schema/sessions.ts (modified, +63/-0)
• src/gateway/protocol/schema/types.ts (modified, +4/-0)
• src/gateway/server-methods-list.ts (modified, +2/-0)
• src/gateway/server-methods/sessions.ts (modified, +129/-0)
• src/gateway/server.sessions.archived.test.ts (added, +155/-0)
• src/gateway/session-transcript-files.archive-discovery.test.ts (added, +113/-0)
• src/gateway/session-transcript-files.fs.ts (modified, +101/-0)
• src/gateway/session-utils.fs.ts (modified, +22/-0)
• src/gateway/session-utils.ts (modified, +15/-0)
• src/gateway/session-utils.types.ts (modified, +9/-0)
• ui/src/i18n/locales/en.ts (modified, +10/-0)
• ui/src/ui/app-render.ts (modified, +6/-0)
• ui/src/ui/app-view-state.ts (modified, +2/-0)
• ui/src/ui/app.ts (modified, +3/-0)
• ui/src/ui/controllers/sessions.test.ts (modified, +1/-0)
• ui/src/ui/controllers/sessions.ts (modified, +72/-0)
• ui/src/ui/types.ts (modified, +27/-0)
• ui/src/ui/views/sessions.test.ts (modified, +3/-0)
• ui/src/ui/views/sessions.ts (modified, +309/-67)