Client chat 네임스페이스
client.chat의 모든 메서드 입력, 출력, 사용 예시.
Client chat 네임스페이스
client.chat은 UI에 보이는 conversation history를 저장하고 조회하는 persistence 표면입니다. Agent lifecycle과 분리되어 있으므로, agent process가 없어도 chat session과 message는 존재할 수 있습니다.
chat.listSessions()
Signature
await client.chat.listSessions(): Promise<{ sessions: ChatSession[] }>Returns
type ChatSession = {
id: string;
label: string;
type: string;
meta: Record<string, unknown> | null;
cwd: string | null;
created_at: string;
};Example
const { sessions } = await client.chat.listSessions();chat.createSession(opts?)
Signature
await client.chat.createSession(opts?: {
id?: string;
label?: string;
type?: string;
meta?: Record<string, unknown>;
}): Promise<{
status: "created";
id: string;
meta: Record<string, unknown> | null;
}>Input
| Field | Required | Description |
|---|---|---|
id | no | 외부 앱이 conversation ID를 직접 정할 때 사용합니다. |
label | no | UI에 표시할 이름입니다. |
type | no | background, main 같은 application-level 분류입니다. 기본값은 background입니다. |
meta | no | 임의의 application metadata입니다. |
Example
const { id } = await client.chat.createSession({
label: "Support thread",
type: "main",
meta: { source: "sidebar" },
});chat.removeSession(session)
Signature
await client.chat.removeSession(session: string): Promise<{ status: "deleted" }>Notes
- 저장된 chat session과 그 message를 삭제합니다.
- 같은 ID의 agent runtime이 active라면 agent lifecycle 정리도 별도로 고려해야 합니다.
chat.listMessages(session, opts?)
Signature
await client.chat.listMessages(
session: string,
opts?: { since?: number },
): Promise<{ messages: ChatMessage[] }>Returns
type ChatMessage = {
id: number;
session_id: string;
actor: "user" | "assistant" | "system";
kind: "text" | "thinking" | "tool_use" | "tool_result" | "status" | "error";
content: string;
embeds: Record<string, { mime_type: string; path: string; meta?: Record<string, unknown> }> | null;
meta: Record<string, unknown> | null;
created_at: string;
updated_at: string;
};Example
const { messages } = await client.chat.listMessages("default");
const newer = await client.chat.listMessages("default", { since: lastSeenId });chat.createMessage(session, opts)
Signature
await client.chat.createMessage(session: string, opts: {
actor: "user" | "assistant" | "system";
kind: "text" | "thinking" | "tool_use" | "tool_result" | "status" | "error";
content?: string;
embeds?: Record<string, { mime_type: string; path: string; meta?: Record<string, unknown> }>;
meta?: Record<string, unknown>;
}): Promise<{ status: "created"; id: number }>Input model
| Field | Description |
|---|---|
actor | 누가 만든 block인지 나타냅니다. user, assistant, system 중 하나입니다. |
kind | 어떤 종류의 block인지 나타냅니다. Text, thinking, tool use, tool result, status, error를 구분합니다. |
content | 표시할 text입니다.  형태로 embed reference를 포함할 수 있습니다. |
embeds | binary attachment metadata입니다. |
meta | kind별 structured overlay입니다. |
Example
const { id } = await client.chat.createMessage("default", {
actor: "user",
kind: "text",
content: "Please review this file.",
});Notes
- Agent가 생성한 message는 보통 server route가 자동 저장합니다.
- UI가 직접 만든 message나 import한 history를 저장할 때 이 메서드를 사용하십시오.
actor와kind설계 이유는 actor와 kind 정규화를 참고하십시오.
chat.clearMessages(session)
Signature
await client.chat.clearMessages(session: string): Promise<{ status: "cleared" }>Use it when conversation 자체는 남겨두고 message만 reset해야 할 때 사용합니다. 예를 들어 session picker에는 남기되 대화 내용을 비우는 경우입니다.