meshagent-agents-ts

TypeScript agent chat session and transport helpers for Meshagent applications.

It provides:

• Agent message constants and JSON models for the Meshagent agent protocol.
• Chat clients and thread sessions for sending turns over Meshagent room messaging.
• Dataset helpers for thread lists and generated images.

Install

npm install @meshagent/meshagent-agents @meshagent/meshagent

In this repository workspace the package is available from meshagent-agents-ts.

Imports

import {
  AgentMessage,
  MessagingChatClient,
  ImagesDataset,
  DatasetThreadStorageRepository,
  TurnStart,
  agentInputContent,
} from "@meshagent/meshagent-agents";

Agent Messages

Every protocol message is represented by a class with toJson() and can be parsed with AgentMessage.fromJson(...).

import {
  AgentMessage,
  TurnStart,
  agentInputContent,
} from "@meshagent/meshagent-agents";

const message = new TurnStart({
  threadId: "dataset://threads/example",
  content: agentInputContent({
    text: "Summarize this file.",
    attachments: ["dataset://assets/files/report.pdf"],
  }),
  provider: "openai",
  model: "gpt-5.4",
});

const wirePayload = message.toJson();
const parsed = AgentMessage.fromJson(wirePayload);

The package exports the message type constants as well, for example agentTurnStartType, agentThreadStartedType, and agentToolCallApprovalRequestedType.

Chat Client

MessagingChatClient sends and receives agent protocol messages through a Meshagent RoomClient messaging channel. The target agent participant must advertise supports_agent_messages: true; optionally pass agentName to select one named agent.

import {
  MessagingChatClient,
  agentTextContentDeltaType,
} from "@meshagent/meshagent-agents";
import type { RoomClient } from "@meshagent/meshagent";

const room: RoomClient = /* create and start your room client */;

const chat = new MessagingChatClient({ room, agentName: "assistant" });
await chat.start();

const { session, threadPath, realtimeConnection } = await chat.startThread({
  message: "Create a project plan.",
  attachments: [],
  provider: "openai",
  model: "gpt-5.4",
});

console.log(threadPath, realtimeConnection);

await session.sendText({
  text: "Make it shorter and include risks.",
  attachments: [],
});

for await (const event of chat.events) {
  if (event.message.type === agentTextContentDeltaType) {
    const delta = event.message as typeof event.message & { text: string };
    process.stdout.write(delta.text);
  }
}

You can also open an existing thread directly:

const session = chat.openThread("dataset://threads/existing");

await session.sendText({
  text: "Continue from the last answer.",
  attachments: [],
});

await session.interruptTurn("turn-id");
await session.changeModel({ provider: "openai", model: "gpt-5.4" });
await session.close();

ChatThreadSession tracks local pending inputs in session.pendingInputs. Pending input state is updated when accepted, started, steered, rejected, ended, or cleared messages arrive from the agent.

Custom Transports

Use BaseChatClient if you want to send agent messages through another transport. Implement sendAgentMessage(...) and feed inbound messages back through handleAgentMessage(...).

import {
  AgentMessage,
  BaseChatClient,
} from "@meshagent/meshagent-agents";

class MyChatClient extends BaseChatClient {
  async sendAgentMessage(
    message: AgentMessage,
    options: { attachment?: Uint8Array } = {},
  ): Promise<void> {
    await sendOverMyTransport(message.toJson(), options.attachment);
  }
}

const client = new MyChatClient();
const session = client.openThread("dataset://threads/custom");

Thread List Storage

DatasetThreadStorageRepository stores thread list metadata in a Meshagent dataset table. The URL format is dataset://[namespace...]/table.

import {
  DatasetThreadStorageRepository,
  ThreadListEntry,
} from "@meshagent/meshagent-agents";

const threads = new DatasetThreadStorageRepository({
  room,
  path: "dataset://agents/default/threads",
});

await threads.open();

await threads.addOrUpdateThread(new ThreadListEntry({
  path: "dataset://threads/thread-1",
  name: "Planning",
  createdAt: new Date().toISOString(),
  modifiedAt: new Date().toISOString(),
}));

console.log(threads.entries());

await threads.renameThread("dataset://threads/thread-1", "Launch Planning");
await threads.deleteThread("dataset://threads/thread-1");
await threads.close();

Image Dataset

ImagesDataset creates and writes to an images table with binary image data and metadata. ImageDatasetClient can read image records by ID or by dataset://.../images?id=... URI.

import {
  ImagesDataset,
  ImageDatasetClient,
} from "@meshagent/meshagent-agents";

const images = new ImagesDataset({
  room,
  namespace: ["agents", "default"],
});

const saved = await images.save({
  data: pngBytes,
  mimeType: "image/png",
  createdBy: "assistant",
  annotations: { prompt: "blue product sketch" },
});

const record = await images.readRecord(saved.id);
console.log(record?.mimeType, record?.data.byteLength);

const ref = ImageDatasetClient.datasetUriReference(
  `dataset://agents/default/images?id=${saved.id}`,
);
console.log(ref.namespace, ref.table, ref.id);

Development

npm run build
npm test

The build emits ESM, Node CommonJS, and browser CommonJS outputs under dist/.