ConversationManager

High-level conversation controller built on top of ArlopassClient. Handles context-window management, summarization, tool calling, and message pinning.

import { ConversationManager } from "@arlopass/web-sdk";

Constructor options

Prop	Type	Default	Description
`client` required	`ArlopassClient`	—	Connected ArlopassClient instance.
`maxTokens`	`number`	—	Context window limit in tokens. Auto-detected from the selected model if omitted.
`reserveOutputTokens`	`number`	`1024`	Tokens reserved for the model's response.
`systemPrompt`	`string`	—	System prompt prepended to every request.
`summarize`	`boolean`	`false`	Enable automatic summarization when the context window fills.
`summarizationPrompt`	`string`	"Summarize the following conversation concisely…"	Custom prompt used for summarization.
`tools`	`ToolDefinition[]`	`[]`	Tool definitions the model can call.
`maxToolRounds`	`number`	`5`	Maximum consecutive tool-call rounds before returning text.
`primeTools`	`boolean`	`false`	Enable tool priming for all messages globally.
`hideToolCalls`	`boolean`	`false`	Strip tool-call markup from responses globally.

Properties

Prop	Type	Default	Description
`maxTokens`	`number`	—	Configured context window limit (readonly getter).

Methods

Prop	Type	Default	Description
`send`	`(content: string, options?: PinOptions) => Promise<ChatMessage>`	—	Send a user message and receive a complete response. Executes tool calls automatically if handlers are defined.
`stream`	`(content: string, options?: PinOptions) => AsyncIterable<ConversationStreamEvent>`	—	Send a user message and stream the response. Yields chunk, done, tool_call, tool_result, and tool_priming_* events.
`addMessage`	`(message: ChatMessage, options?: PinOptions) => void`	—	Manually add a message to the conversation history.
`getMessages`	`() => readonly ChatMessage[]`	—	Get all messages including the system prompt.
`getContextWindow`	`() => readonly ChatMessage[]`	—	Get the messages that would be sent in the next request (after summarization/truncation).
`getTokenCount`	`() => number`	—	Estimated total tokens in the current context window.
`getContextInfo`	`() => ContextWindowInfo`	—	Returns a snapshot of context window usage: maxTokens, usedTokens, reservedOutputTokens, remainingTokens, and usageRatio (0–1).
`setPin`	`(index: number, pinned: boolean) => void`	—	Toggle pin status of a message by index. Pinned messages survive summarization.
`clear`	`() => void`	—	Remove all messages from the conversation.
`submitToolResult`	`(toolCallId: string, result: string) => void`	—	Submit a result for a manual tool call (tools without a handler).

PinOptions

Options passed to send, stream, and addMessage.

Prop	Type	Default	Description
`pinned`	`boolean`	—	Pin the message so it survives context-window summarization.
`primeTools`	`boolean`	—	Force tool priming for this message (overrides manager-level setting).
`hideToolCalls`	`boolean`	—	Hide tool call markup for this message (overrides manager-level setting).

ConversationStreamEvent

Discriminated union yielded by stream(). Extends the base ChatStreamEvent with tool and priming events.

type ConversationStreamEvent =
  | { type: "chunk"; delta: string; index: number; correlationId: string }
  | { type: "done"; correlationId: string }
  | {
      type: "tool_call";
      toolCallId: string;
      name: string;
      arguments: Record<string, unknown>;
      matchRange: { start: number; end: number };
    }
  | { type: "tool_result"; toolCallId: string; name: string; result: string }
  | { type: "tool_priming_start"; message: string }
  | { type: "tool_priming_match"; tools: readonly string[] }
  | { type: "tool_priming_end" };

ContextWindowInfo

Returned by getContextInfo(). Provides a snapshot of context window usage — useful for building token meters, "context full" warnings, and adaptive UI that responds to how much space is left.

type ContextWindowInfo = Readonly<{ 
  maxTokens: number; // Context window size for the model
  usedTokens: number; // Tokens currently in the context window
  reservedOutputTokens: number; // Tokens reserved for model output
  remainingTokens: number; // Tokens left for new input
  usageRatio: number; // 0–1 fraction of input budget used
}>;

Example

const manager = new ConversationManager({
  client,
  systemPrompt: "You are a helpful assistant.",
  tools: [
    { name: "search", description: "Search", handler: async () => "results" },
  ],
});

// Non-streaming
const reply = await manager.send("What is the weather?");

// Streaming
for await (const event of manager.stream("Tell me more")) {
  if (event.type === "chunk") process.stdout.write(event.delta);
  if (event.type === "tool_call") console.log("Tool:", event.name);
}

// Context window usage
const info = manager.getContextInfo();
console.log(
  `${info.usedTokens}/${info.maxTokens} tokens (${Math.round(info.usageRatio * 100)}%)`,
);
console.log(`${info.remainingTokens} tokens remaining for input`);