Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.
Python agent-orchestrationaiai-agentschatopsdiscordlangchainmcpmicrosoft-teamsmulti-agentopen-sourceopenaiself-hostedslack
import { randomUUID } from 'node:crypto';
import { join } from 'node:path';
import { isDeepStrictEqual } from 'node:util';
import {
IMPORTED_TURN_PREFIX,
SessionReplica,
commandSchema,
eventBytes,
hasOwnActivity,
serverEventSchema,
} from '@switch-console/shared/session-v1';
import type {
Answer,
Attachment,
Command,
HostBody,
Origin,
Request,
ServerEvent,
Session,
Snapshot,
} from '@switch-console/shared/session-v1';
import { z } from 'zod';
import { ProviderConversationUnavailableError } from '../adapter';
import type {
ConversationHistoryTurn,
ProviderAdapter,
ProviderSessionStartInput,
TurnAttachment,
} from '../adapter';
import type { TokenUsage, TurnOutcome, UserInputAnswers } from '../events';
import type { ProviderRuntimeEvent } from '../events';
import { ChatProjector, ITEM_PART_CHARACTERS, itemParts } from '../session-v1/chat-projector';
import { ATTACHMENT_MIME_TYPES } from './attachments';
import { Journal } from './journal';
import { fitModelCatalog } from './model-catalog';
import { ReasoningBuffer, type HostReasoningList } from './reasoning-buffer';
import type { Redactions } from './redaction';
import { ToolDetailBuffer } from './tool-detail-buffer';
export const hostInboxRecordSchema = z.discriminatedUnion('type', [
z.object({ type: z.literal('accepted'), command: commandSchema }),
z.object({ type: z.literal('dispatched'), commandId: z.string() }),
z.object({
type: z.literal('finished'),
commandId: z.string(),
// What the turn spent; absent from a host that predates it, or when the provider said nothing.
usage: z
.array(
z.object({
model: z.string(),
inputTokens: z.number().int().nonnegative(),
outputTokens: z.number().int().nonnegative(),
cacheReadTokens: z.number().int().nonnegative(),
cacheWriteTokens: z.number().int().nonnegative(),
})
)
.optional(),
}),
z.object({ type: z.literal('native'), nativeSessionId: z.string() }),
z.object({ type: z.literal('stopped') }),
z.object({ type: z.literal('resumed'), operationId: z.string() }),
z.object({ type: z.literal('reset-started') }),
z.object({ type: z.literal('reset-completed') }),
z.object({ type: z.literal('model'), id: z.string(), options: z.record(z.string(), z.string()) }),
/** The host posts this turn's reply to its room itself: decided once, before posting. */
z.object({ type: z.literal('room-reply'), commandId: z.string() }),
]);
/**
* The notices that end a continued conversation's import, either way. Read
* back from the event journal rather than recorded in the inbox, whose
* records an older host could not read.
*/
const HISTORY_SETTLED = new Set(['HISTORY_IMPORTED', 'HISTORY_UNAVAILABLE']);
type RecordEntry = z.infer<typeof hostInboxRecordSchema>;
export type HostSessionStart = {
session: Session;
resumeOperationId?: string;
authenticate?: () => Promise<void>;
input: ProviderSessionStartInput;
epochAuthority?: 'server';
resetEpoch?: () => Promise<string>;
stageAttachments?: (attachments: Attachment[]) => Promise<TurnAttachment[]>;
/**
* Posts to a room as the agent, raising when the post did not land. Absent
* where the host has no way to reach the agent's rooms.
*/
replyToRoom?: (reply: RoomReply) => Promise<void>;
/** Service tokens to scrub from every event before it is recorded; none when absent. */
redactions?: Redactions;
/**
* The session continues a native conversation started outside Switch, so
* its transcript starts with that conversation's turns, and a conversation
* that cannot be resumed is never quietly replaced by a new one.
*/
importHistory?: boolean;
/**
* Told each time the provider asks to run a connector's tool, before the
* request is published, so a notice it raises comes ahead of the card.
*/
connectorApproval?: (connector: string) => void;
};
/** What the host posts for a turn a room message started that ended without the agent posting. */
export type RoomReply = { roomId: string; threadId: string | null; body: string };
type PendingQuestion = { request: Request; options: Map<string, string> };
/**
* What Switch recorded for a request: for an approval, `answer` is the chosen
* option; for questions, `answers` holds one answer per question. Both are
* null for an expiry.
*/
export type ApprovalOutcome = {
requestId: string;
kind: 'approval' | 'questions';
state: 'answered' | 'expired';
answer: string | null;
answers: Answer[] | null;
answeredBy: string | null;
};
/** Execution owner for a local-only session. Shared server leases are an external boundary. */
export class HostedSession {
private readonly projector: ChatProjector;
private replica: SessionReplica;
private readonly commands = new Map<string, Command>();
private readonly dispatched = new Set<string>();
private readonly finished = new Set<string>();
private readonly roomReplies = new Set<string>();
private historyImported = false;
private readonly postedTurns = new Set<string>();
/** Turns whose posts to the room were refused, with the last refusal. */
private readonly failedPosts = new Map<string, string>();
private readonly usage = new Map<string, TokenUsage[]>();
private readonly resumeOperations = new Set<string>();
private readonly queue: Command[] = [];
private readonly questions = new Map<string, PendingQuestion>();
private readonly listeners = new Set<(event: ServerEvent) => void>();
/** Recent reasoning, in memory only: never published, journaled or replayed. */
private readonly reasoningBuffer = new ReasoningBuffer();
/** Recent tool input and output, in memory only, under the same rules as reasoning. */
private readonly toolDetails = new ToolDetailBuffer();
private activeTurn: string | null = null;
private serial: Promise<unknown> = Promise.resolve();
private eventSerial: Promise<unknown> = Promise.resolve();
private publishing: Promise<unknown> = Promise.resolve();
private nativeId: string | null = null;
private fault: Error | null = null;
private shuttingDown = false;
private modelGeneration = 0;
private stopped = false;
private resetting = false;
private resetPending = false;
private decisionPending = false;
private decisionCode = 'RESET_OUTCOME_UNKNOWN';
private readonly unsubscribe: () => void;
private readonly timer: ReturnType<typeof setInterval>;
private constructor(
readonly config: HostSessionStart,
private readonly adapter: ProviderAdapter,
private readonly events: Journal<ServerEvent>,
private readonly inbox: Journal<RecordEntry>
) {
// Every host from this one on runs `message.retry`; one built before says nothing, meaning no.
config.session.capabilities.retry = true;
const snapshot: Snapshot = {
contractVersion: 1,
throughSequence: 0,
session: structuredClone(config.session),
turns: [],
items: [],
requests: [],
commandStatuses: [],
notices: [],
nextPageToken: null,
};
// Replay old history before announcing the recovered generation.
const first = events.records.find((event) => event.body.type === 'session.upsert');
if (first?.body.type === 'session.upsert')
snapshot.session = structuredClone(first.body.session);
this.replica = new SessionReplica(snapshot);
for (const event of events.records) {
if (
event.body.type === 'session.upsert' &&
event.body.session.epoch !== this.replica.snapshot().session.epoch
) {
const prior = this.replica.snapshot();
prior.session = event.body.session;
this.replica = new SessionReplica(prior);
}
this.replica.apply(event);
if (event.body.type === 'notice' && HISTORY_SETTLED.has(event.body.code))
this.historyImported = true;
}
for (const record of inbox.records) {
if (record.type === 'accepted') this.commands.set(record.command.commandId, record.command);
if (record.type === 'dispatched') this.dispatched.add(record.commandId);
if (record.type === 'finished') {
this.finished.add(record.commandId);
if (record.usage) this.usage.set(record.commandId, record.usage);
}
if (record.type === 'native') this.nativeId = record.nativeSessionId;
if (record.type === 'stopped') this.stopped = true;
if (record.type === 'resumed') {
this.resumeOperations.add(record.operationId);
this.stopped = false;
}
if (record.type === 'reset-started') {
this.nativeId = null;
this.resetPending = true;
}
if (record.type === 'reset-completed') this.resetPending = false;
if (record.type === 'model') config.input.model = { id: record.id, options: record.options };
if (record.type === 'room-reply') this.roomReplies.add(record.commandId);
}
this.projector = new ChatProjector(config.session, config.redactions ?? null);
this.unsubscribe = adapter.subscribe((event) => {
if (event.sessionId !== config.session.sessionId) return;
this.reasoningBuffer.ingest(event, this.config.session.epoch, Date.now());
this.toolDetails.ingest(event, this.config.session.epoch);
// Process cleanup leaves this conversation available for recovery.
// An explicit session.stop is handled before shutdown and remains terminal.
if (
this.shuttingDown &&
!this.stopped &&
(event.type === 'session.exited' ||
(event.type === 'session.state.changed' && event.status === 'stopped'))
)
return;
this.eventSerial = this.eventSerial
.then(() => this.providerEvent(event))
.catch((error: unknown) => this.fail(error));
});
this.timer = setInterval(() => {
this.eventSerial = this.eventSerial
.then(() => this.publishAll(this.projector.flush(Date.now(), false)))
.catch((error: unknown) => this.fail(error));
}, 250);
this.timer.unref();
}
static async start(
root: string,
config: HostSessionStart,
adapter: ProviderAdapter
): Promise<HostedSession> {
const events = await Journal.load(join(root, 'events.jsonl'), (input) =>
serverEventSchema.parse(input)
);
const inbox = await Journal.load(join(root, 'inbox.jsonl'), (input) =>
hostInboxRecordSchema.parse(input)
);
const host = new HostedSession(config, adapter, events, inbox);
try {
if (config.resumeOperationId && !host.resumeOperations.has(config.resumeOperationId)) {
await inbox.append({ type: 'resumed', operationId: config.resumeOperationId });
host.resumeOperations.add(config.resumeOperationId);
host.stopped = false;
}
const recovered = events.records.length > 0;
if (recovered) {
const snapshot = host.replica.snapshot();
for (const request of snapshot.requests)
if (request.state === 'open' || request.state === 'submitting')
await host.publish({
type: 'request.settled',
requestId: request.requestId,
revision: request.revision + 1,
outcome: 'interrupted',
commandId: null,
result: null,
});
for (const turn of snapshot.turns)
if (turn.status === 'running' || turn.status === 'queued')
await host.publish({ ...turn, status: 'interrupted' });
for (const command of host.commands.values()) {
const status = host
.snapshot()
.commandStatuses.find((s) => s.commandId === command.commandId);
if (!status || status.status === 'accepted' || status.status === 'dispatched')
await host.publish({
type: 'command.status',
commandId: command.commandId,
status: 'unknown',
code: 'HOST_RESTARTED',
message: 'The host restarted before confirming the command. It will not resend it.',
});
if (command.body.type === 'message.send' && !host.finished.has(command.commandId))
await host.publish({
type: 'notice',
level: 'warning',
code: 'TURN_INTERRUPTED',
message: host.dispatched.has(command.commandId)
? 'The host restarted during a turn. Its execution outcome is uncertain; the turn was not resent.'
: 'A queued turn was interrupted by the host restart and was not sent to the provider.',
});
}
if (host.stopped) {
host.config.session = { ...config.session, status: 'stopped' };
const stoppedSnapshot = host.replica.snapshot();
stoppedSnapshot.session = host.config.session;
host.replica = new SessionReplica(stoppedSnapshot);
await host.publish({ type: 'session.upsert', session: host.config.session });
clearInterval(host.timer);
host.unsubscribe();
return host;
}
if (host.resetPending) {
await host.awaitResetDecision(
'RESET_OUTCOME_UNKNOWN',
'A reset was interrupted and its outcome is unknown. Start a fresh conversation to continue; earlier messages stay in the transcript.'
);
return host;
}
// A session whose provider never opened a conversation (its first
// start failed) has nothing to resume: it starts one below. One that
// continues a conversation resumes the copy it was started with.
if (!host.nativeId && host.providerAnswered())
throw new Error('Cannot recover a session without its native provider ID.');
if (config.epochAuthority !== 'server') config.session.epoch = randomUUID();
const next = host.replica.snapshot();
config.session.models = next.session.models;
config.session.context = next.session.context;
next.session = structuredClone(config.session);
host.replica = new SessionReplica(next);
}
await host.publish({ type: 'session.upsert', session: structuredClone(config.session) });
if (config.importHistory) {
// Without the copy to resume, starting would open a new conversation
// in place of the one this session was made to continue.
const continued = config.input.resume?.nativeSessionId;
if (!continued)
throw new Error(
'This session continues a conversation started outside Switch, but no copy of it was recorded to resume.'
);
if (!host.historyImported) await host.importHistory(continued);
}
const native = await host.startProvider({
...config.input,
...(host.nativeId ? { resume: { nativeSessionId: host.nativeId } } : {}),
});
await host.inbox.append({ type: 'native', nativeSessionId: native.nativeSessionId });
host.nativeId = native.nativeSessionId;
await host.eventSerial;
void host
.refreshModels()
.catch(async (error: unknown) => {
if (host.shuttingDown) return;
await host.publish({
type: 'notice',
level: 'warning',
code: 'MODEL_CATALOG_UNAVAILABLE',
message: `Could not load provider models: ${String(error)}`,
});
})
.catch((error: unknown) => host.fail(error));
return host;
} catch (error) {
if (
error instanceof ProviderConversationUnavailableError &&
(host.nativeId || config.input.resume)
) {
await host.eventSerial;
// Nothing the provider said is lost when it never answered (a session
// whose turns all failed while its CLI was signed out, say): start a
// new conversation rather than ask. The copy of a conversation this
// session was started to continue was answered before Switch had it;
// a fresh one it started since was not.
const resuming = host.nativeId ?? config.input.resume?.nativeSessionId;
const copy = config.importHistory ? config.input.resume?.nativeSessionId : undefined;
if (!host.providerAnswered() && (copy === undefined || resuming !== copy)) {
try {
await host.startFresh();
return host;
} catch (fresh) {
await host.fail(fresh);
await host.shutdown();
throw fresh;
}
}
await host.awaitResetDecision('NATIVE_CONVERSATION_UNAVAILABLE', error.message);
return host;
}
await host.fail(error);
await host.shutdown();
throw error;
}
}
/**
* Whether the provider has ever answered in this session. Turns copied in
* from a conversation this session continues are not its own answers.
*/
private providerAnswered(): boolean {
const snapshot = this.replica.snapshot();
return hasOwnActivity({
items: snapshot.items.filter((item) => item.kind === 'assistant-message'),
turns: snapshot.turns.filter((turn) => turn.status === 'completed'),
});
}
/** Start a new provider conversation in place of one that cannot be resumed. */
private async startFresh(): Promise<void> {
const { resume: _resume, ...fresh } = this.config.input;
const native = await this.startProvider(fresh);
await this.inbox.append({ type: 'native', nativeSessionId: native.nativeSessionId });
this.nativeId = native.nativeSessionId;
await this.eventSerial;
void this.refreshModels()
.catch(async (error: unknown) => {
if (this.shuttingDown) return;
await this.publish({
type: 'notice',
level: 'warning',
code: 'MODEL_CATALOG_UNAVAILABLE',
message: `Could not load provider models: ${String(error)}`,
});
})
.catch((error: unknown) => this.fail(error));
await this.publish({
type: 'notice',
level: 'info',
code: 'CONVERSATION_STARTED_FRESH',
message:
'Started a new provider conversation: the earlier one was never saved by the provider, so there was nothing to resume.',
});
}
/**
* Publishes the earlier turns of the native conversation this session
* continues, ahead of any of its own: the most recent ones, up to
* {@link HISTORY_ITEM_LIMIT} items, a batch to a journal write, under ids
* marked as imported (`IMPORTED_TURN_PREFIX`). Settled by the notice that
* ends it. An import a crash cut short runs again on the next start and
* publishes only what it had not; an item the conversation itself repeats
* is published once.
*
* A conversation that cannot be read, or whose turns cannot be recorded, is
* said in the transcript, once, and does not stop the session: resuming is
* what decides whether the conversation is there, and asks before replacing
* it.
*/
private async importHistory(nativeSessionId: string): Promise<void> {
let turns: ConversationHistoryTurn[];
try {
if (!this.adapter.conversationHistory)
throw new Error(`${this.config.session.provider} cannot read its saved conversations.`);
turns = await this.adapter.conversationHistory(
nativeSessionId,
this.config.input.cwd,
this.config.input.env
);
} catch (error) {
await this.historyUnavailable(error);
return;
}
const shown = recentTurns(turns, HISTORY_ITEM_LIMIT);
// What an import a crash cut short already published stays as it was, and
// an id the conversation repeats is published the first time only:
// published again it could differ (a token scrubbed since, or another
// entry's text), and two versions of one revision are a conflict the
// transcript refuses.
const present = this.replica.snapshot();
const publishedTurns = new Set(present.turns.map((turn) => turn.turnId));
const publishedItems = new Set(present.items.map((item) => item.itemId));
const bodies: HostBody[] = [];
let shortened = false;
for (const turn of shown) {
const turnId = `${IMPORTED_TURN_PREFIX}${turn.turnId}`;
if (!publishedTurns.has(turnId)) {
publishedTurns.add(turnId);
bodies.push({ type: 'turn.upsert', turnId, status: 'completed', commandId: null });
}
for (const item of turn.items) {
// Scrubbed whole before it is cut, as the chat projector does, so no
// part carries a token in pieces that the scrub of each part would miss.
const scrubbed = this.config.redactions
? this.config.redactions.text(item.text)
: item.text;
const characters = Array.from(scrubbed);
if (characters.length > HISTORY_TEXT_LIMIT) shortened = true;
const text =
characters.length > HISTORY_TEXT_LIMIT
? `${characters.slice(0, HISTORY_TEXT_LIMIT - 1).join('')}…`
: scrubbed;
const title = this.config.redactions ? this.config.redactions.text(item.title) : item.title;
const parts = itemParts(
{
itemId: `${IMPORTED_TURN_PREFIX}${item.itemId}`,
turnId,
revision: 1,
kind: item.kind,
status: item.status,
title: Array.from(title).slice(0, ITEM_PART_CHARACTERS).join(''),
text: '',
attachments: [],
origin: null,
},
text,
1
);
for (const part of parts) {
if (publishedItems.has(part.itemId)) continue;
publishedItems.add(part.itemId);
bodies.push({ type: 'item.upsert', item: part });
}
}
}
const total = turns.reduce((count, turn) => count + turn.items.length, 0);
const kept = shown.reduce((count, turn) => count + turn.items.length, 0);
try {
// Batched to spare a flush to disk per event, and bounded in bytes too,
// so no one write is larger than a single event could already make it.
let batch: HostBody[] = [];
let batchBytes = 0;
for (const body of bodies) {
const bytes = Buffer.byteLength(JSON.stringify(body));
if (
batch.length &&
(batch.length >= HISTORY_BATCH || batchBytes + bytes > HISTORY_BATCH_BYTES)
) {
await this.publishBatch(batch);
batch = [];
batchBytes = 0;
}
batch.push(body);
batchBytes += bytes;
}
if (batch.length) await this.publishBatch(batch);
await this.publish({
type: 'notice',
level: 'info',
code: 'HISTORY_IMPORTED',
message: `${kept < total ? `Above are the last ${kept} of the ${total} messages and tool calls in the conversation this session continues; the earlier ones are not shown here.` : 'Above is the conversation this session continues.'} It was copied when the session started, and the agent has all of it. The original is unchanged.${shortened ? ' Long messages are cut short here.' : ''}`,
});
} catch (error) {
await this.historyUnavailable(error);
return;
}
this.historyImported = true;
}
/**
* Says in the transcript why the earlier turns of the conversation this
* session continues are not shown, or not all of them, and settles the
* import so it is said once.
*/
private async historyUnavailable(error: unknown): Promise<void> {
await this.publish({
type: 'notice',
level: 'warning',
code: 'HISTORY_UNAVAILABLE',
message: `Could not show the earlier turns of the conversation this session continues: ${error instanceof Error ? error.message : String(error)}`,
});
this.historyImported = true;
}
private async startProvider(input: ProviderSessionStartInput) {
const [authentication, provider] = await Promise.allSettled([
Promise.resolve().then(() => this.config.authenticate?.()),
this.adapter.startSession(input),
]);
if (authentication.status === 'rejected') throw authentication.reason;
if (provider.status === 'rejected') throw provider.reason;
return provider.value;
}
private async awaitResetDecision(code: string, message: string): Promise<void> {
this.decisionPending = true;
this.decisionCode = code;
this.queue.length = 0;
this.activeTurn = null;
this.config.session.status = 'error';
this.config.session.capabilities = {
...this.config.session.capabilities,
reset: true,
modelChange: false,
compact: false,
attachmentMimeTypes: [],
};
const snapshot = this.replica.snapshot();
snapshot.session = structuredClone(this.config.session);
this.replica = new SessionReplica(snapshot);
await this.publish({ type: 'session.upsert', session: structuredClone(this.config.session) });
await this.publish({ type: 'notice', level: 'error', code, message });
}
/** Reads how full the context window is and publishes it; unknown when the read fails. */
private async refreshContext(): Promise<void> {
if (!this.adapter.contextUsage) return;
const { sessionId, epoch } = this.config.session;
let usage: Awaited<ReturnType<NonNullable<ProviderAdapter['contextUsage']>>> = null;
try {
usage = await this.adapter.contextUsage(sessionId);
} catch (error) {
console.warn(`Could not read context usage for session ${sessionId}: ${String(error)}`);
}
if (this.shuttingDown || this.resetting || epoch !== this.config.session.epoch) return;
this.config.session.context = usage
? {
usedTokens: Math.max(0, Math.round(usage.usedTokens)),
windowTokens:
usage.windowTokens && usage.windowTokens > 0 ? Math.round(usage.windowTokens) : null,
updatedAt: new Date().toISOString(),
}
: null;
await this.publish({ type: 'session.upsert', session: structuredClone(this.config.session) });
}
private async refreshModels(): Promise<void> {
const generation = ++this.modelGeneration;
const compact =
Boolean(this.adapter.compactSession) &&
(!this.adapter.canCompact || (await this.adapter.canCompact(this.config.session.sessionId)));
const modelsResult = this.adapter.listModels
? await this.adapter.listModels(this.config.session.sessionId)
: undefined;
if (this.shuttingDown || generation !== this.modelGeneration) return;
this.config.session.capabilities.compact = compact;
if (!modelsResult) {
this.updateAttachmentCapabilities();
await this.publish({ type: 'session.upsert', session: structuredClone(this.config.session) });
return;
}
let models = modelsResult;
const previousModels = this.replica.snapshot().session.models;
if (!models.length && previousModels?.length) {
models = previousModels;
await this.publish({
type: 'notice',
level: 'warning',
code: 'MODEL_CATALOG_CACHED',
message:
'The provider did not return a model catalog on resume. Showing the last known choices; the provider will validate each change.',
});
}
const selected = this.config.input.model
? { id: this.config.input.model.id, options: this.config.input.model.options ?? {} }
: null;
const fitted = fitModelCatalog(models, selected?.id ?? null);
this.config.session.models = fitted.models;
this.config.session.model = selected;
this.config.session.capabilities.modelChange = Boolean(
fitted.models.length && this.adapter.setModel
);
this.updateAttachmentCapabilities();
await this.publish({ type: 'session.upsert', session: structuredClone(this.config.session) });
if (fitted.omitted || fitted.optionsDropped)
await this.publish({
type: 'notice',
level: 'warning',
code: 'MODEL_CATALOG_TRUNCATED',
message: fitted.omitted
? `The provider offers ${models.length} models, more than a session can list: only ${fitted.models.length} are offered here, without their options. Narrow the providers it is signed in to, or pick a model in its own settings.`
: `The provider offers ${models.length} models: they are listed without their options, which would not fit. The selected model keeps its own.`,
});
}
private updateAttachmentCapabilities(): void {
const session = this.config.session;
const model = session.models?.find((entry) => entry.id === session.model?.id);
session.capabilities.attachmentMimeTypes = this.config.stageAttachments
? ATTACHMENT_MIME_TYPES.filter(
(mime) => model?.imageInput !== false || !mime.startsWith('image/')
)
: [];
}
notice(message: string): Promise<void> {
return this.publish({ type: 'notice', level: 'error', code: 'ROOM_DELIVERY_FAILED', message });
}
/** A service the session reaches some other way than through Switch: said, not silent. */
serviceFallback(message: string): Promise<void> {
return this.publish({ type: 'notice', level: 'warning', code: 'SERVICE_FALLBACK', message });
}
roomDeliveryResumed(): Promise<void> {
return this.publish({
type: 'notice',
level: 'info',
code: 'ROOM_DELIVERY_RESUMED',
message: 'Room messages are reaching this session again.',
});
}
roomBacklogDelivered(count: number): Promise<void> {
return this.publish({
type: 'notice',
level: 'info',
code: 'ROOM_BACKLOG_DELIVERED',
message: `${count} room message(s) received while the conversation could not continue are now being delivered to the fresh conversation.`,
});
}
startingFreshForRoom(): Promise<void> {
return this.publish({
type: 'notice',
level: 'warning',
code: 'FRESH_START_FOR_ROOM',
message: `A room message arrived while the conversation could not continue (${this.decisionCode}). Starting a fresh conversation to answer it; earlier messages stay in the transcript.`,
});
}
/** A conversation that cannot continue without an explicit reset. */
get resetDecisionPending(): boolean {
return this.decisionPending;
}
/** Work the provider is doing outside any turn, such as background subagents. */
get backgroundWorkRunning(): boolean {
return this.adapter.hasBackgroundWork?.(this.config.session.sessionId) ?? false;
}
snapshot(): Snapshot {
return this.replica.snapshot();
}
/**
* The reasoning and tool details still held for `turnIds` (all buffered
* turns when null), for this epoch.
*/
reasoning(turnIds: string[] | null): HostReasoningList {
const epoch = this.config.session.epoch;
return {
...this.reasoningBuffer.list(epoch, turnIds),
tools: this.toolDetails.list(epoch, turnIds),
};
}
replay(after: number): { events: ServerEvent[]; throughSequence: number } {
return {
events: structuredClone(this.events.records.filter((event) => event.sequence > after)),
throughSequence: this.replica.snapshot().throughSequence,
};
}
/** Hear every event as it is recorded, after it is on disk. Returns the unsubscribe. */
onPublished(listener: (event: ServerEvent) => void): () => void {
this.listeners.add(listener);
return () => this.listeners.delete(listener);
}
/** What `turnId` spent, as its provider reported when it ended. */
usageOf(turnId: string): TokenUsage[] {
return this.usage.get(turnId) ?? [];
}
/**
* The agent posted to a room, through one of the Switch tools: the running
* turn has answered, so the host has nothing to post for it.
*/
agentPostedToRoom(): void {
if (this.activeTurn) this.postedTurns.add(this.activeTurn);
}
/** A post to the room in the running turn was refused: why, the last one kept. */
agentPostFailed(reason: string): void {
if (this.activeTurn) this.failedPosts.set(this.activeTurn, reason);
}
/** Where the command that started `turnId` came from, if a command started it. */
originOf(turnId: string): Origin | null {
return this.commands.get(turnId)?.origin ?? null;
}
/**
* Apply what Switch recorded for one of this session's approval requests:
* a person's answer, or the request running out of time. Serialised with
* commands, since both settle the same requests. Returns false when the
* request is no longer open here — already answered another way, or
* resolved by the provider — which leaves nothing to apply.
*/
applyApprovalOutcome(outcome: ApprovalOutcome): Promise<boolean> {
const result = this.serial.then(() => this.applyOutcome(outcome));
this.serial = result.catch(() => {});
return result;
}
private async applyOutcome(outcome: ApprovalOutcome): Promise<boolean> {
if (this.shuttingDown) throw new Error('HOST_STOPPING');
const pending = this.questions.get(outcome.requestId);
const current = this.snapshot().requests.find((r) => r.requestId === outcome.requestId);
if (!pending || current?.state !== 'open') return false;
const content = pending.request.content;
if (content.kind !== outcome.kind)
throw new Error(
`INVALID_ANSWER: Switch recorded a ${outcome.kind} outcome for request ${outcome.requestId}, which asks for ${content.kind}.`
);
const sessionId = this.config.session.sessionId;
const commandId = `approval:${outcome.requestId}`;
let respond: () => Promise<void>;
let settled: Extract<HostBody, { type: 'request.settled' }>['outcome'];
let result: Extract<HostBody, { type: 'request.settled' }>['result'];
if (outcome.state === 'expired') {
// Declined rather than cancelled, and questions left unanswered: a
// cancel interrupts the whole turn, and nobody answering is not a reason
// to stop the agent's other work.
respond =
content.kind === 'approval'
? () => this.adapter.respondToRequest(sessionId, outcome.requestId, 'decline')
: () => this.adapter.respondToUserInput(sessionId, outcome.requestId, {});
settled = 'expired';
result = null;
} else if (content.kind === 'approval') {
const option = content.options.find((x) => x.optionId === outcome.answer);
if (!option)
throw new Error(
`INVALID_ANSWER: Switch recorded option ${outcome.answer} for request ${outcome.requestId}, which it never offered.`
);
respond = () => this.adapter.respondToRequest(sessionId, outcome.requestId, option.decision);
const cancelled = option.decision === 'cancel';
settled = cancelled ? 'cancelled' : 'answered';
result = cancelled ? null : { kind: 'approval', optionId: option.optionId };
} else {
const answers = outcome.answers;
if (answers === null)
throw new Error(
`INVALID_ANSWER: Switch recorded request ${outcome.requestId} as answered without any answers.`
);
checkQuestionAnswers(content, answers);
const provided = userInputAnswers(pending, answers);
respond = () => this.adapter.respondToUserInput(sessionId, outcome.requestId, provided);
settled = 'answered';
result = { kind: 'questions', answers };
}
// An expiry is marked submitting too, so the provider resolving the
// request as a result is not read as it resolving the request on its own.
const fromConsole = outcome.answeredBy?.startsWith('user:') ?? false;
await this.publish({
type: 'request.submitting',
requestId: outcome.requestId,
revision: current.revision,
commandId,
actorId: outcome.answeredBy ?? 'switch',
surface: fromConsole ? 'console' : 'switch-web',
});
try {
await respond();
} catch (error) {
await this.publish({
type: 'request.settled',
requestId: outcome.requestId,
revision: current.revision + 1,
outcome: 'provider-error',
commandId,
result: null,
});
throw error;
}
await this.publish({
type: 'request.settled',
requestId: outcome.requestId,
revision: current.revision + 1,
outcome: settled,
commandId,
result,
});
this.questions.delete(outcome.requestId);
return true;
}
command(input: Command): Promise<Snapshot['commandStatuses'][number]> {
const command = commandSchema.parse(input);
const result = this.serial.then(() => this.accept(command));
this.serial = result.catch(() => {});
return result;
}
/** Resolves once every command and outcome queued before it has been taken or refused. */
barrier(): Promise<void> {
const result = this.serial.then(() => {});
this.serial = result;
return result;
}
/**
* A retry as the room message it repeats: the message's turn run again, under
* the retry's own id and tied to the same message, so nothing is posted twice
* and the new turn shows where the failed one did. Only a turn that ended
* without an answer is run again.
*/
private retried(command: Command): Command {
if (command.body.type !== 'message.retry') return command;
const { messageId } = command.body;
const original = [...this.commands.values()]
.filter(
(each) =>
each.body.type === 'message.send' &&
each.origin.messageId === messageId &&
each.commandId !== command.commandId
)
.at(-1);
if (!original || original.body.type !== 'message.send')
throw new Error('NOT_FOUND: this session has no turn for that message to run again.');
const turn = this.snapshot().turns.find((each) => each.turnId === original.commandId);
if (turn?.status !== 'error' && turn?.status !== 'interrupted')
throw new Error('SESSION_BUSY: only a turn that ended without an answer can run again.');
return { ...command, origin: original.origin, body: original.body };
}
private async accept(command: Command): Promise<Snapshot['commandStatuses'][number]> {
if (this.shuttingDown) throw new Error('HOST_STOPPING');
const { session } = this.snapshot();
if (command.sessionId !== session.sessionId) throw new Error('NOT_FOUND: session mismatch.');
// Asked again (a double press, a reconnect replaying it): the answer it already has.
if (command.body.type === 'message.retry' && this.commands.has(command.commandId))
return this.status(command.commandId);
command = this.retried(command);
const previous = this.commands.get(command.commandId);
if (previous) {
if (!isDeepStrictEqual(previous, command)) throw new Error('IDEMPOTENCY_CONFLICT');
return this.status(command.commandId);
}
if (this.fault) throw this.fault;
if (command.epoch !== session.epoch) throw new Error('STALE_EPOCH');
const body = command.body;
if (this.decisionPending && body.type !== 'session.reset' && body.type !== 'session.stop')
throw new Error(
`UNSUPPORTED_CAPABILITY: ${this.decisionCode} — start a fresh conversation first.`
);
if (body.type === 'message.send') {
if (this.stopped) throw new Error('Session stop has been requested.');
if (body.delivery !== 'queue')
throw new Error('UNSUPPORTED_CAPABILITY: host currently accepts queued messages.');
if (eventBytes(command) > 60 * 1024)
throw new Error('PAYLOAD_TOO_LARGE: message exceeds the local host limit.');
if (body.attachments.length && !this.config.stageAttachments)
throw new Error('UNSUPPORTED_CAPABILITY: attachment staging is not configured.');
if (
body.attachments.some(
(file) => !session.capabilities.attachmentMimeTypes.includes(file.mimeType)
)
)
throw new Error(
'UNSUPPORTED_CAPABILITY: the selected provider model does not accept this attachment type.'
);
if (session.status !== 'ready' && session.status !== 'running')
throw new Error('Session is not ready.');
} else if (
body.type !== 'turn.interrupt' &&
body.type !== 'session.stop' &&
body.type !== 'session.reset' &&
body.type !== 'session.compact' &&
body.type !== 'session.model.set' &&
body.type !== 'request.answer'
)
throw new Error('UNSUPPORTED_CAPABILITY');
if (
body.type === 'session.reset' ||
body.type === 'session.model.set' ||
body.type === 'session.compact'
) {
const decisionReset =
this.decisionPending && body.type === 'session.reset' && session.status === 'error';
if (
this.activeTurn ||
this.queue.length ||
(session.status !== 'ready' && !decisionReset) ||
this.snapshot().requests.some((r) => r.state === 'open' || r.state === 'submitting')
)
throw new Error('SESSION_BUSY: finish or interrupt the current turn first.');
if (
body.type === 'session.reset' &&
(!session.capabilities.reset ||
(this.config.epochAuthority === 'server' && !this.config.resetEpoch))
)
throw new Error('UNSUPPORTED_CAPABILITY: reset needs a generation authority.');
if (
body.type === 'session.compact' &&
(!session.capabilities.compact || !this.adapter.compactSession)
)
throw new Error('UNSUPPORTED_CAPABILITY: native compaction is unavailable.');
if (
body.type === 'session.model.set' &&
(!session.capabilities.modelChange || !this.adapter.setModel)
)
throw new Error('UNSUPPORTED_CAPABILITY: model changes are unavailable.');
}
if (body.type === 'session.model.set') {
const model = session.models?.find((entry) => entry.id === body.modelId);
if (
!model ||
Object.entries(body.options).some(([key, value]) => !model.options[key]?.includes(value))
)
throw new Error('UNSUPPORTED_MODEL: choose an offered model and options.');
}
if (body.type === 'request.answer') this.validateAnswer(command);
await this.inbox.append({ type: 'accepted', command });
this.commands.set(command.commandId, command);
await this.publish({
type: 'command.status',
commandId: command.commandId,
status: 'accepted',
code: null,
message: null,
});
try {
if (body.type === 'message.send') {
const turnId = command.commandId;
this.projector.bindTurn(turnId, {
commandId: command.commandId,
origin: command.origin,
});
await this.publish({
type: 'turn.upsert',
turnId,
commandId: command.commandId,
status: 'queued',
});
await this.publish({
type: 'item.upsert',
item: {
itemId: `user-${command.commandId}`,
turnId,
revision: 1,
kind: 'user-message',
status: 'completed',
title: '',
text: body.text,
attachments: body.attachments,
origin: command.origin,
},
});
this.queue.push(command);
} else if (body.type === 'session.compact') {
await this.inbox.append({ type: 'dispatched', commandId: command.commandId });
this.dispatched.add(command.commandId);
this.config.session.status = 'running';
await this.publish({
type: 'session.upsert',
session: structuredClone(this.config.session),
});
await this.publish({
type: 'notice',
level: 'info',
code: 'COMPACTION_STARTED',
message: 'Compacting provider context…',
});
let timeout: ReturnType<typeof setTimeout>;
try {
await Promise.race([
this.adapter.compactSession!(session.sessionId),
new Promise<never>((_, reject) => {
timeout = setTimeout(
() => reject(new Error('Native compaction outcome is unknown after 180 seconds.')),
180000
);
}),
]);
await this.eventSerial;
await this.publish({
type: 'notice',
level: 'info',
code: 'COMPACTION_COMPLETED',
message: 'Provider context compaction completed. The transcript remains available.',
});
this.config.session.status = 'ready';
await this.publish({
type: 'session.upsert',
session: structuredClone(this.config.session),
});
void this.refreshContext().catch((error: unknown) => this.fail(error));
} catch (error) {
await this.fail(error);
throw error;
} finally {
clearTimeout(timeout!);
}
} else if (body.type === 'session.model.set') {
await this.inbox.append({ type: 'dispatched', commandId: command.commandId });
this.dispatched.add(command.commandId);
await this.adapter.setModel!(session.sessionId, {
id: body.modelId,
options: body.options,
});
await this.inbox.append({ type: 'model', id: body.modelId, options: body.options });
this.config.input.model = { id: body.modelId, options: body.options };
this.config.session.model = { id: body.modelId, options: body.options };
this.updateAttachmentCapabilities();
await this.publish({
type: 'session.upsert',
session: structuredClone(this.config.session),
});
await this.publish({
type: 'notice',
level: 'info',
code: 'MODEL_CHANGED',
message: `Model changed to ${body.modelId}.`,
});
} else if (body.type === 'session.reset') {
await this.inbox.append({ type: 'dispatched', commandId: command.commandId });
this.dispatched.add(command.commandId);
await this.inbox.append({ type: 'reset-started' });
this.nativeId = null;
this.resetPending = true;
this.resetting = true;
this.modelGeneration++;
try {
if (this.adapter.hasSession(session.sessionId))
await this.adapter.stopSession(session.sessionId);
await this.eventSerial;
const epoch = this.config.resetEpoch ? await this.config.resetEpoch() : randomUUID();
this.config.session.epoch = epoch;
this.config.session.status = 'starting';
this.config.session.context = null;
const snapshot = this.snapshot();
snapshot.session = structuredClone(this.config.session);
this.replica = new SessionReplica(snapshot);
await this.publish({
type: 'session.upsert',
session: structuredClone(this.config.session),
});
const { resume: _resume, ...fresh } = this.config.input;
const native = await this.startProvider(fresh);
await this.inbox.append({ type: 'native', nativeSessionId: native.nativeSessionId });
this.nativeId = native.nativeSessionId;
await this.eventSerial;
await this.inbox.append({ type: 'reset-completed' });
this.resetPending = false;
this.decisionPending = false;
await this.refreshModels();
await this.publish({
type: 'notice',
level: 'info',
code: 'CONTEXT_RESET',
message:
'Started a fresh provider conversation. Earlier messages remain in the transcript for reference.',
});
} catch (error) {
await this.fail(error);
throw error;
} finally {
this.resetting = false;
}
} else if (body.type === 'turn.interrupt') {
if (body.turnId !== this.activeTurn) throw new Error('Turn is no longer active.');
await this.inbox.append({ type: 'dispatched', commandId: command.commandId });
this.dispatched.add(command.commandId);
await this.adapter.interruptTurn(session.sessionId);
} else if (body.type === 'session.stop') {
await this.inbox.append({ type: 'dispatched', commandId: command.commandId });
this.dispatched.add(command.commandId);
await this.inbox.append({ type: 'stopped' });
this.stopped = true;
for (const queued of this.queue)
await this.publish({
type: 'turn.upsert',
turnId: queued.commandId,
commandId: queued.commandId,
status: 'interrupted',
});
this.queue.length = 0;
if (this.adapter.hasSession(session.sessionId))
await this.adapter.stopSession(session.sessionId);
else {
this.config.session.status = 'stopped';
await this.publish({
type: 'session.upsert',
session: structuredClone(this.config.session),
});
}
} else await this.answer(command);
await this.publish({
type: 'command.status',
commandId: command.commandId,
status: 'applied',
code: null,
message: null,
});
if (body.type === 'message.send')
void this.runNext().catch((error: unknown) => this.fail(error));
} catch (error) {
if (body.type === 'session.model.set') await this.fail(error);
if (body.type === 'request.answer') {
const request = this.snapshot().requests.find((r) => r.requestId === body.requestId);
if (request?.state === 'submitting')
await this.publish({
type: 'request.settled',
requestId: request.requestId,
revision: request.revision + 1,
outcome: 'provider-error',
commandId: command.commandId,
result: null,
});
}
await this.publish({
type: 'command.status',
commandId: command.commandId,
status: this.dispatched.has(command.commandId) ? 'unknown' : 'rejected',
code: this.dispatched.has(command.commandId) ? 'OUTCOME_UNKNOWN' : 'PROVIDER_ERROR',
message: String(error),
});
}
return this.status(command.commandId);
}
async reject(command: Command, error: unknown): Promise<void> {
if (this.fault || this.commands.has(command.commandId)) throw error;
await this.inbox.append({ type: 'accepted', command });
this.commands.set(command.commandId, command);
await this.publish({
type: 'command.status',
commandId: command.commandId,
status: 'rejected',
code: 'COMMAND_REJECTED',
message: String(error),
});
}
status(commandId: string): Snapshot['commandStatuses'][number] {
const status = this.snapshot().commandStatuses.find((value) => value.commandId === commandId);
if (!status) throw new Error('NOT_FOUND: command not found.');
return status;
}
private async runNext(): Promise<void> {
if (this.activeTurn || this.shuttingDown || this.stopped || this.fault) return;
const command = this.queue.shift();
if (!command || command.body.type !== 'message.send') return;
this.activeTurn = command.commandId;
try {
const attachments = command.body.attachments.length
? await this.config.stageAttachments!(command.body.attachments)
: [];
if (this.shuttingDown || this.stopped || this.fault) throw new Error('HOST_STOPPING');
await this.inbox.append({ type: 'dispatched', commandId: command.commandId });
this.dispatched.add(command.commandId);
await this.adapter.sendTurn({
sessionId: this.config.session.sessionId,
turnId: command.commandId,
text: command.body.text,
attachments,
});
} catch (error) {
await this.publish({
type: 'turn.upsert',
turnId: command.commandId,
commandId: command.commandId,
status: 'error',
});
await this.publish({
type: 'notice',
level: 'error',
code: 'TURN_FAILED',
message: String(error),
});
await this.replyIfUnposted(command.commandId, 'error', String(error));
this.activeTurn = null;
void this.runNext().catch((error: unknown) => this.fail(error));
}
}
/**
* Tells the room when a turn a room message started failed without the
* agent posting anywhere — a provider that ended on a quota or sign-in
* error — since the room would otherwise hear nothing about it. A turn that
* simply ended without a post says nothing (`unpostedReply`), and one the
* host cut short on purpose (stopping, parking, a reset) is left alone.
*
* Decided once per turn and recorded before the post, so a restart never
* posts it twice. The post runs beside the session; one that fails is
* logged and noted in the transcript, and nothing else.
*/
private async replyIfUnposted(
turnId: string,
outcome: TurnOutcome,
detail: string | null
): Promise<void> {
const posted = this.postedTurns.delete(turnId);
const failedPost = this.failedPosts.get(turnId) ?? null;
this.failedPosts.delete(turnId);
const reply = this.config.replyToRoom;
if (!reply || posted || this.shuttingDown || this.stopped || this.resetting) return;
if (this.roomReplies.has(turnId)) return;
const origin = this.commands.get(turnId)?.origin;
if (!origin?.roomId || !origin.messageId) return;
const roomId = origin.roomId;
// A turn whose every post was refused ended in silence as far as the room
// could tell: it is told that, once, unless the turn failed and says so already.
const body =
unpostedReply(outcome, detail) ?? (failedPost !== null ? postFailedReply(failedPost) : null);
if (body === null) return;
await this.inbox.append({ type: 'room-reply', commandId: turnId });
this.roomReplies.add(turnId);
void reply({ roomId, threadId: origin.threadId, body })
.then(
() =>
this.publish({
type: 'notice',
level: 'info',
code: 'ROOM_REPLY_POSTED',
message: `The turn ended without the agent posting to room ${roomId}, so the host posted there for it.`,
}),
async (error: unknown) => {
const reason = error instanceof Error ? error.message : String(error);
console.warn(
`Could not tell room ${roomId} that turn ${turnId} ended without a reply: ${reason}`
);
await this.publish({
type: 'notice',
level: 'warning',
code: 'ROOM_REPLY_FAILED',
message: `The turn ended without the agent posting to room ${roomId}, and the host could not post there for it: ${reason}`,
});
}
)
.catch((error: unknown) =>
console.warn(`Could not record the room reply for turn ${turnId}: ${String(error)}`)
);
}
private async providerEvent(event: ProviderRuntimeEvent): Promise<void> {
// A reset stops the old conversation on the way to a fresh one. That stop
// is not the session's: shown, it reads as the session ending.
if (
this.resetting &&
(event.type === 'session.exited' ||
(event.type === 'session.state.changed' && event.status === 'stopped'))
)
return;
if (event.type === 'session.exited') {
for (const request of this.snapshot().requests)
if (request.state === 'open' || request.state === 'submitting')
await this.publish({
type: 'request.settled',
requestId: request.requestId,
revision: request.revision + 1,
outcome: 'interrupted',
commandId: null,
result: null,
});
for (const turn of this.snapshot().turns)
if (turn.status === 'running' || turn.status === 'queued')
await this.publish({ ...turn, status: 'interrupted' });
this.queue.length = 0;
this.activeTurn = null;
this.questions.clear();
}
if (event.type === 'session.started') {
this.nativeId = event.nativeSessionId;
await this.inbox.append({ type: 'native', nativeSessionId: event.nativeSessionId });
}
if (event.type === 'runtime.error' || event.type === 'runtime.warning')
await this.publish({
type: 'notice',
level: event.type === 'runtime.error' ? 'error' : 'warning',
code: 'PROVIDER_NOTICE',
message: event.message,
});
if (event.type === 'request.opened' || event.type === 'user-input.requested') {
const options = new Map<string, string>();
const request: Request = {
requestId: event.requestId,
turnId: event.turnId,
revision: 1,
state: 'open',
expiresAt: null,
content:
event.type === 'request.opened'
? {
kind: 'approval',
title: event.title,
detail: event.detail ?? null,
options: event.options.map((option, index) => ({
...option,
optionId: String(index),
})),
}
: {
kind: 'questions',
title: 'Question from the agent',
questions: event.questions.map((question) => ({
questionId: question.id,
title: question.header ?? '',
prompt: question.question,
multiSelect: question.multiSelect,
allowCustomAnswer: question.allowCustomAnswer,
options: question.options.map((option, index) => {
const optionId = `${question.id}:${index}`;
options.set(optionId, option.value);
return {
optionId,
label: option.label,
description: option.description ?? null,
};
}),
})),
},
};
this.questions.set(request.requestId, { request, options });
if (event.type === 'request.opened' && event.connector !== undefined)
this.config.connectorApproval?.(event.connector);
await this.publish({ type: 'request.opened', request });
}
if (event.type === 'request.resolved' || event.type === 'user-input.resolved') {
const request = this.snapshot().requests.find((r) => r.requestId === event.requestId);
if (request?.state === 'open')
await this.publish({
type: 'request.settled',
requestId: request.requestId,
revision: request.revision + 1,
outcome: 'interrupted',
commandId: null,
result: null,
});
}
if (
(event.type === 'item.started' ||
event.type === 'item.updated' ||
event.type === 'item.completed') &&
event.item.type === 'user_message'
)
return;
// A turn is finished, with what it spent, before anyone can read that it
// ended: its report to Switch is the one chance to count the spend.
if (event.type === 'turn.completed') {
await this.inbox.append({
type: 'finished',
commandId: event.turnId,
...(event.usage.length > 0 ? { usage: event.usage } : {}),
});
this.finished.add(event.turnId);
if (event.usage.length > 0) this.usage.set(event.turnId, event.usage);
}
await this.publishAll(this.projector.ingest(event, Date.now()));
if (event.type === 'turn.completed') {
await this.replyIfUnposted(event.turnId, event.outcome, event.message ?? null);
this.activeTurn = null;
void this.runNext().catch((error: unknown) => this.fail(error));
void this.refreshContext().catch((error: unknown) => this.fail(error));
}
}
private validateAnswer(command: Command): PendingQuestion {
if (command.body.type !== 'request.answer') throw new Error('INVALID_ANSWER');
const body = command.body;
const pending = this.questions.get(body.requestId);
const current = this.snapshot().requests.find((r) => r.requestId === body.requestId);
if (!pending || current?.state !== 'open') throw new Error('REQUEST_CLOSED');
if (current.revision !== body.expectedRevision) throw new Error('STALE_REVISION');
if (body.answer.kind !== pending.request.content.kind) throw new Error('INVALID_ANSWER');
if (body.answer.kind === 'approval' && pending.request.content.kind === 'approval') {
if (
!pending.request.content.options.some(
(x) => x.optionId === (body.answer as { optionId: string }).optionId
)
)
throw new Error('INVALID_ANSWER');
} else if (body.answer.kind === 'questions' && pending.request.content.kind === 'questions')
checkQuestionAnswers(pending.request.content, body.answer.answers);
return pending;
}
private async answer(command: Command): Promise<void> {
if (command.body.type !== 'request.answer') return;
const body = command.body;
const pending = this.validateAnswer(command);
await this.publish({
type: 'request.submitting',
requestId: body.requestId,
revision: body.expectedRevision,
commandId: command.commandId,
actorId: command.origin.actorId,
surface: command.origin.surface,
});
await this.inbox.append({ type: 'dispatched', commandId: command.commandId });
this.dispatched.add(command.commandId);
let cancelled = false;
if (body.answer.kind === 'approval' && pending.request.content.kind === 'approval') {
const option = pending.request.content.options.find(
(x) => x.optionId === (body.answer as { optionId: string }).optionId
)!;
cancelled = option.decision === 'cancel';
await this.adapter.respondToRequest(command.sessionId, body.requestId, option.decision);
} else if (body.answer.kind === 'questions') {
await this.adapter.respondToUserInput(
command.sessionId,
body.requestId,
userInputAnswers(pending, body.answer.answers)
);
}
await this.publish({
type: 'request.settled',
requestId: body.requestId,
revision: body.expectedRevision + 1,
outcome: cancelled ? 'cancelled' : 'answered',
commandId: command.commandId,
result: cancelled ? null : body.answer,
});
this.questions.delete(body.requestId);
}
private publishAll(bodies: HostBody[]): Promise<void> {
return bodies.reduce((tail, body) => tail.then(() => this.publish(body)), Promise.resolve());
}
private publish(body: ServerEvent['body']): Promise<void> {
return this.publishBatch([body]);
}
/** Publishes events in order, recorded with one write to the journal. */
private publishBatch(bodies: ServerEvent['body'][]): Promise<void> {
const pending = this.publishing.then(async () => {
const occurredAt = new Date().toISOString();
const events = bodies.map((body, index) => {
const event: ServerEvent = {
contractVersion: 1,
eventId: randomUUID(),
sessionId: this.config.session.sessionId,
sequence: this.events.records.length + 1 + index,
occurredAt,
// Scrubbed here, once: the journal, Console's view and the activity
// rows Switch shows on the bridges are all made from what is recorded.
body: this.config.redactions ? this.config.redactions.value(body) : body,
};
if (eventBytes(event) > 64 * 1024)
throw new Error('PAYLOAD_TOO_LARGE: event exceeds 64 KiB.');
serverEventSchema.parse(event);
return event;
});
await this.events.appendAll(events);
for (const event of events) {
this.replica.apply(event);
for (const listener of this.listeners) listener(event);
}
});
this.publishing = pending.catch(() => {});
return pending;
}
private async fail(error: unknown): Promise<void> {
if (this.fault) return;
clearInterval(this.timer);
this.fault = error instanceof Error ? error : new Error(String(error));
this.config.session.status = 'error';
try {
try {
await this.publish({
type: 'session.upsert',
session: structuredClone(this.config.session),
});
} catch (upsertError) {
// The failure is recorded even when the session record is what could
// not be: without its model catalog it is a few hundred bytes.
console.error('SDK host could not record its session:', String(upsertError));
const { models: _models, ...session } = structuredClone(this.config.session);
await this.publish({ type: 'session.upsert', session });
}
await this.publish({
type: 'notice',
level: 'error',
code: 'HOST_ERROR',
message: this.fault.message,
});
} catch (persistenceError) {
console.error('SDK host could not persist its failure:', String(persistenceError));
}
}
async shutdown(): Promise<void> {
this.shuttingDown = true;
clearInterval(this.timer);
if (this.adapter.hasSession(this.config.session.sessionId))
await this.adapter.stopSession(this.config.session.sessionId);
await this.serial;
await this.eventSerial;
await this.publishing;
this.unsubscribe();
}
}
/** How many items of a continued conversation's earlier turns a transcript starts with. */
const HISTORY_ITEM_LIMIT = 500;
/** How much of one imported item's text is shown; the agent still has all of it. */
const HISTORY_TEXT_LIMIT = 4 * ITEM_PART_CHARACTERS;
/** How many of a continued conversation's events are recorded with one journal write. */
const HISTORY_BATCH = 100;
/** And how much: no larger than one event may be, so no write is larger than one could be already. */
const HISTORY_BATCH_BYTES = 64 * 1024;
/**
* The most recent turns that together hold no more than `limit` items, oldest
* first. A latest turn larger than that on its own keeps its last `limit`.
*/
export function recentTurns(
turns: ConversationHistoryTurn[],
limit: number
): ConversationHistoryTurn[] {
const kept: ConversationHistoryTurn[] = [];
let items = 0;
for (let index = turns.length - 1; index >= 0; index--) {
const turn = turns[index]!;
if (items + turn.items.length > limit) {
if (kept.length === 0) kept.push({ ...turn, items: turn.items.slice(-limit) });
break;
}
kept.push(turn);
items += turn.items.length;
}
return kept.reverse();
}
/**
* What the host posts for a room turn that ended without the agent posting:
* only that it failed, and why, so a crash is not silent. A turn that
* finished, or that someone stopped, posts nothing: the agent chose not to
* answer, and its final text was never meant for the room.
*/
export function unpostedReply(outcome: TurnOutcome, detail: string | null): string | null {
if (outcome !== 'error') return null;
const hint = REQUEST_TOO_LARGE.test(detail ?? '')
? 'Use !reset to start a fresh session, then send your message again. '
: '';
const reason = detail?.trim() ? `: ${hint}${cap(detail.trim(), 1000)}` : '.';
return `I finished without replying. The turn failed${reason}`;
}
const REQUEST_TOO_LARGE =
/exceeds [\d.]+ ?MB limit|request_too_large|request too large|prompt is too long/i;
/** What the host posts for a turn whose every post to the room was refused. */
export function postFailedReply(reason: string): string {
return `I couldn't post my reply here: ${cap(reason.trim(), 1000)}`;
}
function cap(text: string, limit: number): string {
const characters = Array.from(text);
return characters.length <= limit
? text
: `${characters
.slice(0, limit - 1)
.join('')
.trimEnd()}…`;
}
type QuestionsContent = Extract<Request['content'], { kind: 'questions' }>;
/** Throws INVALID_ANSWER unless `answers` answers every question once, with what it offers. */
function checkQuestionAnswers(content: QuestionsContent, answers: Answer[]): void {
if (
new Set(answers.map((a) => a.questionId)).size !== content.questions.length ||
answers.length !== content.questions.length
)
throw new Error('INVALID_ANSWER');
for (const question of content.questions) {
const answer = answers.find((a) => a.questionId === question.questionId);
if (!answer) throw new Error('INVALID_ANSWER');
const custom = Boolean(answer.customText?.trim());
if (custom && !question.allowCustomAnswer) throw new Error('INVALID_ANSWER');
if (
answer.selectedOptionIds.some((id) => !question.options.some((o) => o.optionId === id)) ||
new Set(answer.selectedOptionIds).size !== answer.selectedOptionIds.length
)
throw new Error('INVALID_ANSWER');
if (
question.multiSelect
? !custom && !answer.selectedOptionIds.length
: Number(custom) + answer.selectedOptionIds.length !== 1
)
throw new Error('INVALID_ANSWER');
}
}
/** Checked answers, as the provider takes them: its own option values and any custom text. */
function userInputAnswers(pending: PendingQuestion, answers: Answer[]): UserInputAnswers {
const provided: UserInputAnswers = {};
const content = pending.request.content;
for (const answer of answers) {
const values = answer.selectedOptionIds.map((id) => pending.options.get(id)!);
if (answer.customText?.trim()) values.push(answer.customText.trim());
const question =
content.kind === 'questions'
? content.questions.find((q) => q.questionId === answer.questionId)!
: null;
provided[answer.questionId] = question?.multiSelect ? values : values[0];
}
return provided;
}