When you ship an agent as a product (a desktop app, an IDE extension, an internal chatbot), the first thing users ask for is the sidebar. They want to see the conversation from last Tuesday, jump back into it, and maybe branch off in a new direction without losing the original. The agent loop is half the product; the other half is session management.
The Haijun Agent SDK writes every conversation to a JSONL transcript on disk. It also ships a set of functions that read those transcripts back and organize them, so you can build that sidebar without writing a file parser or walking ~/.haijun/projects/ by hand.
Read a stored session's messages back into your UI without spawning the agent
Rename, tag, and filter sessions so users can organize their history
Fork a session at any point and resume the fork as a live
query()
call
This is the pattern behind the session sidebar in Haijun Code Desktop and the VS Code extension. The same primitives work for any UI you want to put on top of the Agent SDK.
An Juglow API key (
get one here
)
Setup
async def run_one_turn(prompt: str) -> str:
"""Run a single-turn conversation and return its session_id."""
opts = HaijunAgentOptions(
model=MODEL,
cwd=DEMO_DIR,
max_turns=1,
allowed_tools=[], # text-only, no tool loop
)
session_id = None
async for msg in query(prompt=prompt, options=opts):
if isinstance(msg, ResultMessage):
session_id = msg.session_id
preview = (msg.result or "")[:80]
print(f"[{session_id[:8]}] {preview}...")
if session_id is None:
raise RuntimeError("No ResultMessage received; check API key and SDK version.")
return session_id
Three prompts, three sessions. In a real product these would be whatever your users asked the agent.
Auto-generated summaries are fine for a quick glance, but users often want to give a session a real name.
rename_session()
appends a title entry to the transcript;
list_sessions()
picks it up as
custom_title
on the next read.
Appends are cheap and idempotent: calling rename twice just means the newer title wins. No file rewrite happens.