会话管理

// typescript
const sessionStore = context.store.claudeSessionStore()

// python
session_store = context.store.claude_session_store()

// agents/chat/index.ts
const conversationId = context.conversation_id ?? ''
const sessionStore = context.store.claudeSessionStore()

// 把任意业务 ID 映射成稳定的 UUID sessionId（是 UUID 就原样返回，否则生成并持久化）
const sessionId = await context.store.claudeSessionBinding(conversationId)

// 判断这个 sessionId 之前有没有落过盘：有就 resume 续上，没有就当新会话
// dir 不能省——SessionStore 的 blob key 按项目目录派生，丢了 dir 永远读不回
const info = await getSessionInfo(sessionId, { dir: process.cwd(), sessionStore })

const options: Record<string, any> = { model, systemPrompt, sessionStore }
if (info) {
  options.resume = sessionId       // 恢复已有会话
} else {
  options.sessionId = sessionId    // 新建会话
}

const q = query({ prompt: message, options })

session_store = context.store.claude_session_store()
session_id = await context.store.claude_session_binding(conversation_id)
# 同样：getSessionInfo 判断 resume/new，options 里带上 session_store 和 resume/session_id

// openaiSession 会以 conversation id 为依据自动恢复会话
// typescript
const session = context.store.openaiSession(context.conversation_id)

// python
session = context.store.openai_session(context.conversation_id)

// agents/hitl/index.ts
import { RunState, run } from '@openai/agents'
const RUN_STATE_KEY = 'openai.run-state'

// —— 首轮：跑起来，如果中断就把 RunState 存进 state ——
const result = await run(agent, message, { signal })
if (result.state.getInterruptions().length > 0) {
  await context.store.state.set(RUN_STATE_KEY, result.state.toString())  // 关键：存 RunState
  return json({ status: 'awaiting_approval' })
}
await context.store.state.delete(RUN_STATE_KEY)   // 没中断，跑完了，清掉

// —— 下一轮：带批准/拒绝进来，读回 RunState 还原、续跑 ——
const stored = await context.store.state.get<string>(RUN_STATE_KEY)
const state = await RunState.fromString(agent, stored)   // 还原中断态
const [approval] = state.getInterruptions()
body.approved ? state.approve(approval) : state.reject(approval)
const resumed = await run(agent, state, { signal })      // 从断点续跑

// typescript
const checkpointer = context.store.langgraphCheckpointer
const store = context.store.langgraphStore

// python
checkpointer = context.store.langgraph_checkpointer
store = context.store.langgraph_store

// typescript
const checkpointer = context.store.langgraphCheckpointer
const store = context.store.langgraphStore

// python
checkpointer = context.store.langgraph_checkpointer
store = context.store.langgraph_store

const messageId = await context.store.appendMessage({
  conversationId: context.conversation_id,
  role: 'user',
  content: context.request.body.message,
  userId: context.request.body.userId,
  metadata: { source: 'web' },
})

message_id = await context.store.append_message(
    conversation_id=context.conversation_id,
    role="user",
    content=context.request.body["message"],
    user_id=context.request.body.get("user_id"),
    metadata={"source": "web"},
)

const messages = await context.store.getMessages({
  conversationId: context.conversation_id,
  limit: 50,
})
const reply = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: context.store.toOpenAIInput(messages),
})

messages = await context.store.get_messages(
    conversation_id=context.conversation_id,
    limit=50,
)
reply = await openai_client.chat.completions.create(
    model="gpt-4o",
    messages=context.store.to_openai_input(messages),
)

const updated = await context.store.updateMessage({
  conversationId: context.conversation_id,
  messageId: 'msg_abc123',
  content: 'corrected answer',
  metadata: { edited: true },
})

updated = await context.store.update_message(
    conversation_id=context.conversation_id,
    message_id="msg_abc123",
    content="corrected answer",
    metadata={"edited": True},
)

await context.store.deleteMessage({
  conversationId: context.conversation_id,
  messageId: 'msg_abc123',
})

await context.store.delete_message(
    conversation_id=context.conversation_id,
    message_id="msg_abc123",
)

await context.store.clearMessages({ conversationId: context.conversation_id })

await context.store.clear_messages(conversation_id=context.conversation_id)

const meta = await context.store.getConversation({
  conversationId: context.conversation_id,
})
console.log(meta.messageCount, meta.metadata?.title)

meta = await context.store.get_conversation(
    conversation_id=context.conversation_id,
)
print(meta.message_count, (meta.metadata or {}).get("title"))

const { items, nextCursor } = await context.store.listConversations({
  userId: 'u_123',
  limit: 20,
})

result = await context.store.list_conversations(user_id="u_123", limit=20)
items, next_cursor = result.items, result.next_cursor

await context.store.updateConversation({
  conversationId: context.conversation_id,
  metadata: { title: '产品咨询', tag: null },  // 设标题，删 tag
})

await context.store.update_conversation(
    conversation_id=context.conversation_id,
    metadata={"title": "产品咨询", "tag": None},
)

await context.store.deleteConversation({
  conversationId: context.conversation_id,
})

await context.store.delete_conversation(
    conversation_id=context.conversation_id,
)

const history = await context.store.getMessages({
  conversationId: context.conversation_id,
})
const resp = await anthropic.messages.create({
  model: 'claude-sonnet-4',
  max_tokens: 1024,
  messages: context.store.toAnthropicMessages(history),
})

history = await context.store.get_messages(
    conversation_id=context.conversation_id,
)
resp = await anthropic_client.messages.create(
    model="claude-sonnet-4",
    max_tokens=1024,
    messages=context.store.to_anthropic_messages(history),
)

const history = await context.store.getMessages({
  conversationId: context.conversation_id,
})
const resp = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: context.store.toOpenAIInput(history),
})

history = await context.store.get_messages(
    conversation_id=context.conversation_id,
)
resp = await openai_client.chat.completions.create(
    model="gpt-4o",
    messages=context.store.to_openai_input(history),
)

// 请求开始：读回上一轮状态（没有则 null）
const saved = await context.store.state.get<MyState>('session')

// ... 跑一轮对话 ...

// 请求结束：把最新状态存回去
await context.store.state.set('session', latestState)

saved = await context.store.state.get("session")
# ... 跑一轮 ...
await context.store.state.set("session", latest_state)

interface Message {
  messageId: string                       // msg_xxx（appendMessage 自动生成）
  role: 'user' | 'assistant' | 'system' | 'tool'
  content: any                            // string / array / object（多模态）
  createdAt: number                       // ms 时间戳
  metadata?: Record<string, any>          // 自定义（token 数、tool_call 等）
  updatedAt?: number                      // 仅 updateMessage 后存在
}

interface ConversationMeta {
  conversationId: string
  createdAt: number                       // ms 时间戳
  lastMessageAt: number                   // ms 时间戳
  messageCount: number
  metadata?: Record<string, any>          // 业务自定义（标题、用户、标签等）
}

interface ListConversationsResult {
  items: ConversationMeta[]
  nextCursor?: string                     // 下一页游标，传给 after 参数
  previousCursor?: string                 // 上一页游标，传给 before 参数
}