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 {
  AgentFileContent,
  AgentMessage,
  TurnStart,
  agentInputContent,
} from "@meshagent/meshagent-agents";

const message = new TurnStart({
  threadId: "dataset://threads/example",
  content: agentInputContent({
    text: "Summarize this file.",
    attachments: [new AgentFileContent({
      url: "dataset://assets/files/report.pdf",
      name: "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 {
  AgentTextContentDelta,
  MessagingChatClient,
} 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 instanceof AgentTextContentDelta) {
    process.stdout.write(event.message.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.

WebSocket Chat Client

WebSocketChatClient is the direct MessagePack WebSocket transport. It uses the meshagent-msgpack and meshagent-agent.<token> subprotocols and reconnects by default.

import { WebSocketChatClient } from "@meshagent/meshagent-agents";

const chat = new WebSocketChatClient({
  url: new URL("wss://example.test/messages"),
  token: participantToken,
  participantName: "[email protected]",
});

await chat.start();
const { session } = await chat.startThread({
  message: "Hello",
  attachments: [],
});

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/.

An external E2E harness can validate interoperability with a Rust process agent by starting that agent in a room, then supplying its room participant credentials:

MESHAGENT_TOKEN=... \
MESHAGENT_ROOM=... \
TEST_AGENT_NAME=... \
MESHAGENT_API_URL=... \
npm run test:rust-process-e2e

The runner owns only the TypeScript client. The harness remains responsible for starting and stopping the Rust process agent named by TEST_AGENT_NAME. It must also supply either MESHAGENT_API_URL (preferred for the Rust harness) or MESHAGENT_ROOM_URL, so the client does not silently connect to production.

From this repository, the preferred full interoperability check starts the Rust server and process agent, runs both the Dart and TypeScript suites, and stops the fixture automatically:

rust/meshagent-server-e2e/run-cross-language-e2e.sh