Skip to content

docs(rfd): Add RFD 053 for auto-refresh conversation titles#461

Merged
JeanMertz merged 1 commit intomainfrom
prr31
Mar 19, 2026
Merged

docs(rfd): Add RFD 053 for auto-refresh conversation titles#461
JeanMertz merged 1 commit intomainfrom
prr31

Conversation

@JeanMertz
Copy link
Collaborator

RFD 053 proposes periodic background re-titling of conversations that have accumulated a configurable number of new turns since their title was last generated.

The core design introduces a turn_interval threshold (default 5) under conversation.title.generate.auto_refresh. When a jp query run starts, a background TitleRefreshTask scans all conversations, identifies stale candidates (those where turn_count >= baseline + turn_interval), and re-runs LLM title generation for up to batch_size of them — sorted by least recently activated to avoid churning active conversations.

Key design decisions:

  • A new title_generated_at_turn field on Conversation tracks the turn count when the title was last auto-generated, serving as the staleness baseline.
  • A retain_current field in the title generation schema lets the LLM signal that the existing title is still accurate, advancing the checkpoint without replacing the title.
  • turn_context (default 10) caps how many recent turns are sent to the LLM, keeping costs predictable for long conversations.
  • Manual conversation edit --title "..." writes a ConfigDelta with turn_interval = 0, opting that conversation out of auto-refresh.
  • The full pipeline — scanning, loading, LLM calls — runs off the critical path and respects CancellationToken to avoid delaying CLI exit.

RFD 020 is also updated to reflect that get_conversation_mut (not just get_events_mut) requires a &ConversationLock, as the title refresh sync phase needs to mutate conversation metadata under the same locking invariant.

RFD 053 proposes periodic background re-titling of conversations that
have accumulated a configurable number of new turns since their title
was last generated.

The core design introduces a `turn_interval` threshold (default 5) under
`conversation.title.generate.auto_refresh`. When a `jp query` run
starts, a background `TitleRefreshTask` scans all conversations,
identifies stale candidates (those where `turn_count >= baseline +
turn_interval`), and re-runs LLM title generation for up to `batch_size`
of them — sorted by least recently activated to avoid churning active
conversations.

Key design decisions:

- A new `title_generated_at_turn` field on `Conversation` tracks the
  turn count when the title was last auto-generated, serving as the
  staleness baseline.
- A `retain_current` field in the title generation schema lets the LLM
  signal that the existing title is still accurate, advancing the
  checkpoint without replacing the title.
- `turn_context` (default 10) caps how many recent turns are sent to the
  LLM, keeping costs predictable for long conversations.
- Manual `conversation edit --title "..."` writes a `ConfigDelta` with
  `turn_interval = 0`, opting that conversation out of auto-refresh.
- The full pipeline — scanning, loading, LLM calls — runs off the
  critical path and respects `CancellationToken` to avoid delaying CLI
  exit.

RFD 020 is also updated to reflect that `get_conversation_mut` (not just
`get_events_mut`) requires a `&ConversationLock`, as the title refresh
sync phase needs to mutate conversation metadata under the same locking
invariant.

Signed-off-by: Jean Mertz <git@jeanmertz.com>
@JeanMertz JeanMertz merged commit e4bc697 into main Mar 19, 2026
12 checks passed
@JeanMertz JeanMertz deleted the prr31 branch March 19, 2026 13:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant