chat_message_list

Retrieve and paginate through chat session messages in chronological order to review conversation history and maintain context.

Instructions

List messages in a session with pagination. Returns messages in chronological order.

Input Schema

TableJSON Schema

Name	Required	Description
`sessionId`	Yes	UUID of the session.
`limit`	No	Maximum number of messages to return. Default: 50.
`offset`	No	Number of messages to skip (for pagination). Default: 0.

Implementation Reference

src/layers/messages.ts:98-105 (handler)
The listMessages handler function that wraps the adapter's getMessages method. This is the main handler called by the tool registration when executing chat_message_list.
```
export async function listMessages(
  adapter: ChatAdapter,
  sessionId: string,
  limit = 50,
  offset = 0,
): Promise<ChatMessage[]> {
  return adapter.getMessages(sessionId, limit, offset);
}
```

src/adapters/env.ts:545-549 (handler)

The actual getMessages implementation in the environment adapter. Reads messages from GitHub storage and applies pagination with offset and limit parameters.

async getMessages(sessionId, limit, offset) {
  const msgs = await readMessages(githubToken, stateRepo, sessionId);
  if (!msgs) return [];
  return msgs.messages.slice(offset, offset + limit);
},

src/app.ts:207-235 (registration)

Tool registration for chat_message_list including its name, description, input schema (sessionId, limit, offset), and the execute function that calls layers.messages.listMessages.

  name: "chat_message_list",
  description:
    "List messages in a session with pagination. Returns messages in chronological order.",
  inputSchema: {
    type: "object",
    properties: {
      sessionId: {
        type: "string",
        description: "UUID of the session.",
      },
      limit: {
        type: "number",
        description: "Maximum number of messages to return. Default: 50.",
      },
      offset: {
        type: "number",
        description: "Number of messages to skip (for pagination). Default: 0.",
      },
    },
    required: ["sessionId"],
  },
  execute: async (args) =>
    layers.messages.listMessages(
      adapter,
      args.sessionId as string,
      args.limit as number | undefined,
      args.offset as number | undefined,
    ),
},

src/types.ts:30-40 (schema)

ChatMessage interface defining the output schema returned by chat_message_list. Includes id, sessionId, role, content, model, inputTokens, outputTokens, timestamp, and metadata fields.

export interface ChatMessage {
  id: string;             // UUID v4
  sessionId: string;
  role: "user" | "assistant" | "system";
  content: string;
  model?: ChatModel;      // set on assistant messages
  inputTokens?: number;   // set on assistant messages
  outputTokens?: number;  // set on assistant messages
  timestamp: string;      // ISO-8601
  metadata?: Record<string, unknown>;
}

src/adapters/env.ts:191-203 (helper)

The readMessages helper function that retrieves the messages.jsonl file from GitHub and parses it into ChatMessage objects. Used by the getMessages adapter method.

async function readMessages(
  token: string,
  stateRepo: string,
  sessionId: string,
): Promise<{ messages: ChatMessage[]; sha: string } | null> {
  const file = await ghGet(token, stateRepo, messagesPath(sessionId));
  if (!file) return null;
  const messages = file.content
    .split("\n")
    .filter((line) => line.trim() !== "")
    .map((line) => JSON.parse(line) as ChatMessage);
  return { messages, sha: file.sha };
}

@git-fabric/chat