Generalize Content-block handling: capability-based API for editable types

[DrumRobot]

Problem

Two related defects in how the Web UI handles Content shapes and exposes per-message capabilities:

1. Categorization gap: categorizeMessage in packages/web/src/lib/utils/message.ts originally assumed Content was always ContentItem[], missing the string and single-ContentItem shapes. This part was resolved by PR fix(web): normalize Content shapes before message categorization #166 (normalizeContent helper).
2. Capability gap (load-bearing concern): per-message capability checks in MessageItem.svelte are ad-hoc derived (isToolResult, hasNonTextBlocks, isEditable) and conflate "which ContentItem.type is this" with "which capability does it support". Result: editable types like tool_result and thinking are blanket-blocked from editing because the assistant-side tool_use pairing concern bled into all non-text shapes. The intent is a type-aware capability API that lets each ContentItem.type opt into edit/delete/copy/export/convert/extract independently.

Origin

CodeRabbit review on PR #97 (6d447a6) flagged scope (1). User testing surfaced scope (2) as the load-bearing intent — categorization alone is "tidy refactoring," but the actual user-facing block is "I cannot edit my tool_result messages."

Scope (a) — Categorize all Content shapes (resolved)

Resolved by PR #166 (merged 2026-06-06 → beta, squash commit bb7f3d6). Not yet synced to main.

Acceptance Criteria for (a)

• All Content shapes (string, single item, array, msg.message.content) correctly categorized — PR fix(web): normalize Content shapes before message categorization #166
• Unit tests covering each Content shape variant — PR fix(web): normalize Content shapes before message categorization #166 (5 new tests)
• No regression in existing message display — PR fix(web): normalize Content shapes before message categorization #166

Scope (b) — Type-aware capability API for editable content (open)

Replace the ad-hoc isEditable derived in MessageItem.svelte with a getCapabilities(content: Content): Capabilities function in packages/web/src/lib/utils/message.ts (or a sibling module). The function returns per-message capability booleans.

Target types (editable side)

ContentItem.type is open (api.ts ContentItem.type: string). The capability matrix covers the types currently observed in session JSONL:

Type	Edit	Delete	Copy	Export	Convert	Extract
text (human/user/assistant)	✅	✅	✅	✅	—	—
tool_result (user side)	✅ (with tool_use_id preservation)	✅	✅	✅	✅ (e.g. tool_result → text)	✅ (extract stdout/stderr/content)
thinking (assistant side)	✅	✅	✅	✅	✅ (thinking → text)	—

Explicitly excluded:

• tool_use (assistant output) — editing breaks tool_use ↔ tool_result pairing invariant. Delete + copy may still apply.
• image, document — not currently observed in session JSONL; revisit when they appear.

Capability API shape (proposed)

export interface Capabilities {
  canEdit: boolean
  canDelete: boolean
  canCopy: boolean
  canExport: boolean
  canConvert: boolean
  canExtract: boolean
}

export const getCapabilities = (msg: Message): Capabilities => {
  // Use normalizeContent(msg.message.content) to get ContentItem[].
  // Inspect items[0].type (and items.some(...)) to drive each boolean.
  // tool_use pairing constraint stays inside this function, not bled into UI.
}

MessageItem.svelte consumes getCapabilities(msg) and renders edit/delete/copy/export/convert/extract affordances accordingly. No more ad-hoc isEditable, isToolResult, hasNonTextBlocks in the component.

Acceptance Criteria for (b)

• getCapabilities(msg) implemented + unit-tested for each (type × capability) combination from the matrix above. (PR fix(core): type-aware message editing — unlock tool_result/thinking editing (issue #123) #200)
• MessageItem.svelte isEditable / isToolResult / hasNonTextBlocks derived removed; UI consumes getCapabilities(msg) instead. (PR fix(core): type-aware message editing — unlock tool_result/thinking editing (issue #123) #200)
• tool_result messages render an edit affordance, preserving tool_use_id and is_error fields on save. (PR fix(core): type-aware message editing — unlock tool_result/thinking editing (issue #123) #200)
• thinking messages render an edit affordance. (PR fix(core): type-aware message editing — unlock tool_result/thinking editing (issue #123) #200)
• Backend (packages/core/src/session/crud.ts editMessageContent) is tool_result-aware and thinking-aware (no silent structured-data drop). (PR fix(core): type-aware message editing — unlock tool_result/thinking editing (issue #123) #200)
• Convert affordance (e.g. tool_result → text, thinking → text) is wired to a UI action + backend path.
• Extract affordance pulls stdout / stderr / content from tool_result into a copyable text block.
• Test fixture with paired tool_use ↔ tool_result verifies the pairing invariant is preserved across edit, delete, convert.
• e2e spec covers each capability per type.
• Plan written before implementation (~/ghq/github.com/es6kr/.ralph/docs/generated/plan-issue-123-content-handling-generalization.md).

Out of scope

• tool_use editing (intentional — pairing invariant).
• image / document content (revisit when they appear in session JSONL).
• Edit conflict resolution across concurrent sessions (separate concern).

[DrumRobot]

Scope (b) implementation — plan + verified results

Implementation is up as draft PR #200.

Approach (per this issue's proposal, with a few decisions):

• getCapabilities(msg): Capabilities lives in packages/web/src/lib/utils/message.ts — the full 6-flag interface is defined; canEdit/canDelete are wired to the UI now, while copy/export/convert/extract flags are computed but unconsumed until Phases B/C
• Phasing: Phase A in PR fix(core): type-aware message editing — unlock tool_result/thinking editing (issue #123) #200 (capability API + tool_result/thinking edit unlock — the load-bearing complaint); Phase B (copy/export) and Phase C (convert/extract) follow as separate PRs, since 4 of the 6 capabilities have no existing UI at all and bundling them would make an unreviewably large change
• canDelete returns true for all types — behavior-preserving (the Delete affordance was never content-gated)
• Prerequisite recovered: normalizeContent (PR fix(web): normalize Content shapes before message categorization #166) had landed on beta but never on main — cherry-picked onto this branch, so Scope (a) reaches main together with this PR

Verified (all green):

• core unit 502/502 — incl. new preservation tests (tool_use_id / is_error / signature / unknown fields survive edits) + a paired tool_use ↔ tool_result fixture
• web unit 100/100 — incl. 12 capability-matrix cases
• e2e message-capabilities.spec.ts 4/4 — tool_result & thinking edit round-trips verified on disk; tool_use exclusion; text-edit regression
• Browser captures attached in the PR body

Backend detail: updateMessageContent resolution order is now text → tool_result → thinking → append-text fallback; non-target blocks are never mutated.