Skip to content

[Feature] Introduce a Session abstraction and multi-session support #79

Description

@arefbehboudi

Background

JavaClaw currently has no explicit session/conversation abstraction. The agent
handles messages per channel (WebSocket chat, Telegram, Discord), identity and
context come from workspace/AGENT.md + workspace/INFO.md + workspace/context/,
and scheduled work runs as JobRunr tasks. There is no per-conversation transcript
object and no isolation between channels, or between scheduled work and live chat.

Current state (from repo)

  • No Session/transcript type; conversation handling is per-channel.
  • Context is workspace-file based (AGENT.md, INFO.md, context/) — global, not per-session.
  • Scheduling via JobRunr; jobrunr.background-job-server.worker-count defaults to 1.

Goal

A Session object with its own id, channel binding, and transcript; N sessions
running in parallel; serialized turns within a session; correct routing and
context scoping.

Acceptance criteria

  • Session type + persistence (reuse H2, or transcript-as-Markdown under workspace/ consistent with the existing file-based model). Fields: id, channelKey, transcript, state, timestamps.
  • Resolve-or-create a session per channelKey (e.g. telegram:<chatId>, discord:<userId>, chat:<wsSession>).
  • One-turn-per-session concurrency guarantee. On Spring Boot 4 / Java 25, model each session's turn on a virtual thread with a per-session lock; never two concurrent turns on the same session id.
  • Session registry with lazy creation + idle eviction.
  • Inbound routing in each channel plugin maps its message to the right session (no cross-channel transcript bleed).
  • Scheduled/JobRunr tasks run under their own session so they do not block live chat; revisit worker-count implications.
  • Context scoping: decide how AGENT.md/INFO.md/context/ load per session, and which context is private vs. shared if a shared/group channel is ever added.
  • Basic session list + switch in the built-in chat UI (htmx/Bulma).

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions