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 type { ChildProcess } from 'node:child_process';
import { readFileSync } from 'node:fs';
import { join } from 'node:path';
import { serverEventSchema, type ServerEvent } from '@switch-console/shared/session-v1';
import { z } from 'zod';
import { killProcessTree } from './process-fence';
import { hostReasoningListSchema, type HostReasoningList } from './reasoning-buffer';
import { Redactions, tokenForms } from './redaction';
import { ServiceCredential } from './service-credential';
import { isStopMessage } from './stop-request';
/**
* How long a session host that has finished may take to exit once it has
* closed its end of the pipe. It exits by itself within this; see
* `HOST_HUNG_UP_MS` for when its parent stops waiting.
*/
export const HOST_EXIT_GRACE_MS = 5000;
/**
* How long a host that hung up its pipe may stay alive before its parent
* kills it. Longer than the host's own grace, so a host that is leaving is
* given the chance to leave on its own.
*/
export const HOST_HUNG_UP_MS = 15000;
/**
* The pipe between a session host and the process that started it.
*
* A session host runs as a child of Console (a local session) or of the
* agent's sidecar (a remote one), and they talk over the IPC channel Node
* opens when the child is spawned: plain JSON messages, in order, private to
* the two of them, closed when either exits. Nothing goes through a file or
* through Switch.
*
* The parent asks (`request`) and the host answers (`reply`); the host also
* pushes every event it records (`event`) and says when it is ready to take
* requests (`ready`). The other way round, the host says which session it is
* (`identity`, again whenever its generation moves) and asks its parent
* (`ask`) for what only the holder of the agent's connection can do: list the
* Switch tools, run one, and post a turn's reply the agent left unposted. The
* parent answers (`answer`).
*/
export const sessionRequestSchema = z.discriminatedUnion('type', [
/** A contract `Command`; validated by the host. */
z.object({
type: z.literal('command'),
command: z.unknown(),
/** Who asked, as the room names them; null for a command from Console. */
requesterName: z.string().nullable(),
/** The command came from a direct chat; absent from a parent older than the field. */
direct: z.boolean().optional(),
}),
/** A room message the agent was addressed with, as the controller routed it. */
z.object({
type: z.literal('room'),
handoff: z.object({
sequence: z.number().int().positive(),
roomId: z.string().min(1),
messageId: z.string().min(1),
event: z.unknown(),
}),
}),
/** The session as the host holds it now. */
z.object({ type: z.literal('snapshot') }),
/** Switch has an answer to one of this session's approval requests. */
z.object({ type: z.literal('approvals') }),
/**
* The reasoning the host still holds for these turns (all of them when
* null). Read-only, never journaled, and only ever asked over a local or SSH
* link: a host that predates it cannot parse it and does not answer.
*/
z.object({ type: z.literal('reasoning'), turnIds: z.array(z.string().min(1)).nullable() }),
]);
export type SessionRequest = z.infer<typeof sessionRequestSchema>;
/** What a host asks its parent, which holds the agent's connection to Switch. */
export const hostAskSchema = z.discriminatedUnion('type', [
/** The Switch tools, as MCP lists them. */
z.object({ type: z.literal('tools') }),
/** One tool call, answered with the MCP tool result. */
z.object({
type: z.literal('tool'),
name: z.string().min(1),
arguments: z.record(z.string(), z.unknown()),
}),
/**
* The host's own post, as the agent, to the room a turn was started from:
* the turn ended without the agent posting there. Refused unless the session
* still attends `roomId`.
*/
z.object({
type: z.literal('room-reply'),
roomId: z.string().min(1),
threadId: z.string().min(1).nullable(),
body: z.string().min(1),
}),
/**
* The room's own instructions, answered with `{ instructions }` ('' for a
* room with none). Refused unless the session still attends `roomId`.
*/
z.object({
type: z.literal('room-instructions'),
roomId: z.string().min(1),
}),
/**
* A token for one of the agent's granted services, answered with a
* `ServiceTokenAnswer`. `rejected` is a token the service refused (Git
* erasing it, or `gh` told 401): the parent stops handing it out.
*/
z.object({
type: z.literal('service-token'),
service: z.string().regex(/^[a-z0-9][a-z0-9-]{0,62}$/),
rejected: z.string().nullable(),
}),
]);
export type HostAsk = z.infer<typeof hostAskSchema>;
/** Which session a host runs: what its tool calls are made as. */
export const hostIdentitySchema = z.strictObject({
agentId: z.string().min(1),
sessionId: z.string().min(1),
hostId: z.string().min(1),
epoch: z.string().min(1),
});
export type HostIdentity = z.infer<typeof hostIdentitySchema>;
/** A host asking, as its parent knows it. */
export type Caller = HostIdentity & { root: string };
/** Answers what the hosts of one agent's sessions ask. */
export type AskHandler = (caller: Caller, ask: HostAsk) => Promise<unknown>;
const answerSchema = z.object({
kind: z.literal('answer'),
id: z.number().int().nonnegative(),
ok: z.boolean(),
value: z.unknown().optional(),
error: z.string().optional(),
});
/** Why a session is busy: one kind per condition, with how many of it. */
export const busyReasonSchema = z.object({
kind: z.enum(['turn_running', 'turn_starting', 'room_pending', 'approval_open', 'reset_waiting']),
count: z.number().int().positive(),
});
export type BusyReason = z.infer<typeof busyReasonSchema>;
export type BusyState = { busy: boolean; reasons: BusyReason[] };
const toChildSchema = z.discriminatedUnion('kind', [
z.object({
kind: z.literal('request'),
id: z.number().int().nonnegative(),
request: sessionRequestSchema,
}),
answerSchema,
/** Answer `busy` once every command queued before this has been taken or refused. */
z.object({ kind: z.literal('busyBarrier'), id: z.number().int().nonnegative() }),
/** Service token values, in every form, that this agent's sessions were handed: scrub them too. */
z.object({ kind: z.literal('redactions'), values: z.array(z.string()) }),
]);
const fromChildSchema = z.discriminatedUnion('kind', [
z.object({ kind: z.literal('ready') }),
z.object({ kind: z.literal('event'), event: serverEventSchema }),
z.object({
kind: z.literal('reply'),
id: z.number().int().nonnegative(),
ok: z.boolean(),
value: z.unknown().optional(),
error: z.string().optional(),
}),
z.object({ kind: z.literal('identity'), identity: hostIdentitySchema }),
z.object({ kind: z.literal('ask'), id: z.number().int().nonnegative(), ask: hostAskSchema }),
z.object({
kind: z.literal('busy'),
busy: z.boolean(),
reasons: z.array(busyReasonSchema),
barrier: z.number().int().nonnegative().optional(),
}),
]);
/** Raised when a session host is not running, or stopped before it answered. */
export class SessionUnavailableError extends Error {
constructor(message: string) {
super(message);
this.name = 'SessionUnavailableError';
}
}
/**
* Raised when a session host stopped on a failure it recorded, and nothing has
* started it again since. Starting it again without changing anything would
* fail the same way, so the caller decides whether to.
*/
export class SessionHostFailedError extends Error {
constructor(readonly failure: string) {
super(`The session host failed: ${failure}`);
this.name = 'SessionHostFailedError';
}
}
/**
* Why the host at this root stopped, from the `supervisor/failure.json` it
* writes before exiting on an error; a plain account of the exit when it
* wrote none.
*/
function recordedFailure(root: string, code: number): string {
try {
const recorded = z
.object({ message: z.string().min(1) })
.safeParse(JSON.parse(readFileSync(join(root, 'supervisor', 'failure.json'), 'utf8')));
if (recorded.success) return recorded.data.message;
console.warn(`The failure the session host at ${root} recorded is unreadable.`);
} catch (error) {
if ((error as NodeJS.ErrnoException).code !== 'ENOENT')
console.warn(`Could not read why the session host at ${root} failed: ${String(error)}`);
}
return `The session host exited with code ${code}.`;
}
const NO_ANSWER = 'The session host did not answer in time.';
type Pending = {
resolve: (value: unknown) => void;
reject: (error: Error) => void;
timer: ReturnType<typeof setTimeout>;
};
type Link = {
child: ChildProcess | null;
ready: boolean;
identity: HostIdentity | null;
/** Why the last host here stopped on an error, until another is started. */
failure: string | null;
nextId: number;
pending: Map<number, Pending>;
waiting: (() => void)[];
subscribers: Set<(event: ServerEvent) => void>;
/** What the running host last said about being busy; null before it has. */
busy: BusyState | null;
barriers: Map<number, Pending>;
/** How many hosts here have exited, so a waiting request can tell one did. */
exits: number;
/** The running host did not answer a `reasoning` request: it predates them. */
noReasoning: boolean;
};
/**
* How long a `reasoning` request waits for its answer. A host that predates
* the request cannot parse it and never answers, so this is how such a host
* is told apart; the link does not ask it again.
*/
const REASONING_TIMEOUT_MS = 5000;
/**
* The parent's end: one link per session state root, re-attached each time
* the supervisor starts the host again.
*/
export class SessionLinks {
/**
* Every service token answered to these hosts. Their supervisor scrubs it
* from what they log, and their parent from what it sends to Switch.
*/
readonly redactions = new Redactions();
/**
* The same tokens by the agent they were issued for, every form of each. A
* session host learns its agent's when it says which session it runs and
* each new one as it is answered, so a token fetched by a sibling session,
* or before this one resumed, is scrubbed from what it publishes too. Only
* the agent's own: no host is handed another agent's tokens.
*/
private readonly agentTokens = new Map<string, Set<string>>();
private readonly links = new Map<string, Link>();
private readonly answerers = new Map<string, AskHandler>();
private readonly exitListeners = new Set<(root: string, identity: HostIdentity | null) => void>();
private readonly readyListeners = new Set<(root: string) => void>();
private readonly failureListeners = new Set<(root: string, failure: string) => void>();
private readonly busyListeners = new Set<(root: string) => void>();
private link(root: string): Link {
let link = this.links.get(root);
if (!link) {
link = {
child: null,
ready: false,
identity: null,
failure: null,
nextId: 0,
pending: new Map(),
waiting: [],
subscribers: new Set(),
busy: null,
barriers: new Map(),
exits: 0,
noReasoning: false,
};
this.links.set(root, link);
}
return link;
}
/** Called by the supervisor with each host it spawns. */
attach(root: string, child: ChildProcess): void {
const link = this.link(root);
link.child = child;
link.ready = false;
link.identity = null;
link.failure = null;
link.busy = null;
link.noReasoning = false;
for (const listener of this.busyListeners) listener(root);
child.on('message', (raw) => {
const parsed = fromChildSchema.safeParse(raw);
if (!parsed.success) {
console.warn(`Ignoring an unreadable message from the session host at ${root}.`);
return;
}
const message = parsed.data;
if (message.kind === 'ready') {
link.ready = true;
for (const wake of link.waiting.splice(0)) wake();
for (const listener of this.readyListeners) listener(root);
} else if (message.kind === 'event') {
for (const subscriber of link.subscribers) subscriber(message.event);
} else if (message.kind === 'identity') {
link.identity = message.identity;
const held = this.agentTokens.get(message.identity.agentId);
if (held?.size) shareRedactions(child, root, [...held]);
} else if (message.kind === 'busy') {
link.busy = { busy: message.busy, reasons: message.reasons };
for (const listener of this.busyListeners) listener(root);
if (message.barrier !== undefined) {
const pending = link.barriers.get(message.barrier);
link.barriers.delete(message.barrier);
if (pending) {
clearTimeout(pending.timer);
pending.resolve(link.busy);
}
}
} else if (message.kind === 'ask') {
const answer = (outcome: { ok: true; value: unknown } | { ok: false; error: string }) => {
if (child.connected)
child.send({ kind: 'answer', id: message.id, ...outcome }, (error) => {
if (error) console.warn(`Could not answer the session host at ${root}: ${error}`);
});
};
const asker = link.identity;
this.answerAsk(root, asker, message.ask).then(
(value) => {
if (asker && message.ask.type === 'service-token' && isTokenAnswer(value))
this.shareToken(asker.agentId, value.token);
answer({ ok: true, value: value ?? null });
},
(error: unknown) =>
answer({ ok: false, error: error instanceof Error ? error.message : String(error) })
);
} else {
const pending = link.pending.get(message.id);
if (!pending) return;
link.pending.delete(message.id);
clearTimeout(pending.timer);
if (message.ok) pending.resolve(message.value);
else pending.reject(new Error(message.error ?? 'The session host refused the request.'));
}
});
// A host that closes its end of the pipe is leaving, and nothing sent
// down the pipe reaches it again. It is gone from here from that moment,
// not from the moment it exits: a host that hung up and stays alive —
// something it started still running — holds its session's lock, so it
// cannot be started again, while every message sent down the pipe fails.
// Requests wait for the next host instead, and one that is still alive
// after `HOST_HUNG_UP_MS` is killed with everything it started, which
// frees the lock and lets its supervisor start it again.
let hungUp: ReturnType<typeof setTimeout> | null = null;
child.once('disconnect', () => {
if (link.child !== child) return;
link.ready = false;
for (const [id, pending] of link.pending) {
clearTimeout(pending.timer);
pending.reject(new SessionUnavailableError('The session host hung up before it answered.'));
link.pending.delete(id);
}
for (const [id, pending] of link.barriers) {
clearTimeout(pending.timer);
pending.reject(new SessionUnavailableError('The session host hung up before it answered.'));
link.barriers.delete(id);
}
hungUp = setTimeout(() => {
if (child.exitCode !== null || child.signalCode !== null) return;
console.warn(
`The session host at ${root} hung up ${HOST_HUNG_UP_MS / 1000} s ago and has not exited; stopping it and what it started.`
);
killHostGroup(child);
}, HOST_HUNG_UP_MS);
hungUp.unref?.();
});
child.once('exit', (code) => {
if (hungUp) clearTimeout(hungUp);
if (link.child !== child) return;
const identity = link.identity;
link.child = null;
link.ready = false;
link.identity = null;
link.busy = null;
link.exits++;
// A non-zero exit is one the supervisor does not recover from: the host
// has already written why.
if (code !== null && code !== 0) link.failure = recordedFailure(root, code);
const failure = link.failure;
for (const [id, pending] of link.pending) {
clearTimeout(pending.timer);
pending.reject(
failure !== null
? new SessionHostFailedError(failure)
: new SessionUnavailableError('The session host stopped before it answered.')
);
link.pending.delete(id);
}
for (const [id, pending] of link.barriers) {
clearTimeout(pending.timer);
pending.reject(new SessionUnavailableError('The session host stopped before it answered.'));
link.barriers.delete(id);
}
// A request waiting for this host to come up learns now that it will not.
for (const wake of link.waiting.splice(0)) wake();
for (const listener of this.busyListeners) listener(root);
for (const listener of this.exitListeners) listener(root, identity);
if (failure !== null) for (const listener of this.failureListeners) listener(root, failure);
});
}
/** Hand a token just answered to every host of the agent it was issued for. */
private shareToken(agentId: string, token: string): void {
const held = this.agentTokens.get(agentId) ?? new Set<string>();
this.agentTokens.set(agentId, held);
const forms = [...new Set(ServiceCredential.of(token).secrets.flatMap(tokenForms))].filter(
(form) => !held.has(form)
);
if (!forms.length) return;
for (const form of forms) held.add(form);
for (const [root, link] of this.links)
if (link.child && link.identity?.agentId === agentId)
shareRedactions(link.child, root, forms);
}
private async answerAsk(
root: string,
identity: HostIdentity | null,
ask: HostAsk
): Promise<unknown> {
if (!identity)
throw new Error('The session host asked its parent before saying which session it runs.');
const handler = this.answerers.get(identity.agentId);
if (!handler)
throw new Error(
`No room watcher is running for agent ${identity.agentId} here, so this session's Switch tools cannot reach Switch. Turn the agent's room connection on in Console.`
);
return handler({ ...identity, root }, ask);
}
/**
* Answer what the hosts of this agent's sessions ask, until the returned
* function is called. One answerer per agent: it is the process holding the
* agent's connection.
*/
answer(agentId: string, handler: AskHandler): () => void {
if (this.answerers.has(agentId))
throw new Error(`Agent ${agentId} already has a watcher answering its sessions here.`);
this.answerers.set(agentId, handler);
return () => {
if (this.answerers.get(agentId) === handler) this.answerers.delete(agentId);
};
}
/** Which session the host at this root last said it runs, or null. */
identity(root: string): HostIdentity | null {
return this.links.get(root)?.identity ?? null;
}
/** Hear each host exit, with the session it last said it ran. */
onExit(listener: (root: string, identity: HostIdentity | null) => void): () => void {
this.exitListeners.add(listener);
return () => this.exitListeners.delete(listener);
}
/** Hear each host say it is ready for requests. */
onReady(listener: (root: string) => void): () => void {
this.readyListeners.add(listener);
return () => this.readyListeners.delete(listener);
}
/** Hear each host stop on a failure, with the failure it recorded. */
onFailure(listener: (root: string, failure: string) => void): () => void {
this.failureListeners.add(listener);
return () => this.failureListeners.delete(listener);
}
/** Why the last host at this root stopped on an error, or null if it did not. */
failure(root: string): string | null {
return this.links.get(root)?.failure ?? null;
}
/** Forgets a recorded failure: something is about to start the host again. */
clearFailure(root: string): void {
const link = this.links.get(root);
if (link) link.failure = null;
}
/** Whether a host is running at this root and ready for requests. */
ready(root: string): boolean {
return this.links.get(root)?.ready === true;
}
/**
* Ask the host, waiting up to `timeoutMs` for one to be ready if it is
* still starting. Refused with `SessionUnavailableError` when none comes,
* and with `SessionHostFailedError` as soon as the host stops on a failure.
*/
request(root: string, request: SessionRequest, timeoutMs: number): Promise<unknown> {
return this.dispatch(root, request, timeoutMs, () => {});
}
/**
* `request`, calling `dispatching` once a host is ready, just before the
* request is sent to it. A throw from `dispatching` refuses the request
* before it reaches the host.
*/
async dispatch(
root: string,
request: SessionRequest,
timeoutMs: number,
dispatching: () => void
): Promise<unknown> {
const link = this.link(root);
const deadline = Date.now() + timeoutMs;
const exits = link.exits;
while (!link.ready || !link.child) {
if (link.failure !== null) throw new SessionHostFailedError(link.failure);
// The host this request was waiting on is gone, and nothing here starts
// another: say so now, so the caller starts it, rather than at the deadline.
if (link.exits !== exits && !link.child)
throw new SessionUnavailableError('The session host stopped before it was ready.');
const remaining = deadline - Date.now();
if (remaining <= 0) throw new SessionUnavailableError('The session host is not running.');
await new Promise<void>((resolve) => {
const timer = setTimeout(done, remaining);
function done() {
clearTimeout(timer);
const at = link.waiting.indexOf(done);
if (at !== -1) link.waiting.splice(at, 1);
resolve();
}
link.waiting.push(done);
});
}
const child = link.child;
// Belt and braces for the 'disconnect' handler above: a send down a
// closed pipe fails anyway, but saying why is clearer than the error.
if (!child.connected)
throw new SessionUnavailableError('The session host hung up and is on its way out.');
dispatching();
const id = link.nextId++;
return new Promise<unknown>((resolve, reject) => {
const timer = setTimeout(
() => {
link.pending.delete(id);
reject(new SessionUnavailableError(NO_ANSWER));
},
Math.max(deadline - Date.now(), 5000)
);
link.pending.set(id, { resolve, reject, timer });
child.send({ kind: 'request', id, request }, (error) => {
if (!error) return;
link.pending.delete(id);
clearTimeout(timer);
reject(new SessionUnavailableError(`The session host could not be reached: ${error}`));
});
});
}
/**
* The reasoning the running host at this root still holds, or null when no
* host is ready there or it predates the request. Never waits for a host to
* start and never raises: reasoning is a nicety, not something to fail on.
*/
async reasoning(root: string, turnIds: string[] | null): Promise<HostReasoningList | null> {
const link = this.links.get(root);
if (!link?.ready || !link.child || link.noReasoning) return null;
const child = link.child;
try {
const answer = hostReasoningListSchema.safeParse(
await this.request(root, { type: 'reasoning', turnIds }, REASONING_TIMEOUT_MS)
);
if (answer.success) return answer.data;
console.warn(`The session host at ${root} answered a reasoning request unreadably.`);
return null;
} catch (error) {
if (
error instanceof SessionUnavailableError &&
error.message === NO_ANSWER &&
link.child === child
) {
link.noReasoning = true;
console.warn(
`The session host at ${root} did not answer a reasoning request; it predates them, so it is not asked again.`
);
}
return null;
}
}
/** The roots with a host process running, ready or not. */
live(): string[] {
return [...this.links].flatMap(([root, link]) => (link.child ? [root] : []));
}
/** Hear each host start and exit, and each change in what a host says about being busy. */
onBusy(listener: (root: string) => void): () => void {
this.busyListeners.add(listener);
return () => this.busyListeners.delete(listener);
}
/** What the running host at this root last said about being busy; null if none is running or it has not said. */
busy(root: string): BusyState | null {
return this.links.get(root)?.busy ?? null;
}
/**
* Ask the running host for its busy state once every command sent to it
* before now has been taken or refused. Refused with
* `SessionUnavailableError` when no host is running, it exits first, or it
* does not answer within `timeoutMs`.
*/
barrier(root: string, timeoutMs: number): Promise<BusyState> {
const link = this.link(root);
const child = link.child;
if (!child || !link.ready)
return Promise.reject(new SessionUnavailableError('The session host is not running.'));
const id = link.nextId++;
return new Promise<BusyState>((resolve, reject) => {
const timer = setTimeout(() => {
link.barriers.delete(id);
reject(new SessionUnavailableError('The session host did not answer its busy barrier.'));
}, timeoutMs);
link.barriers.set(id, { resolve: resolve as (value: unknown) => void, reject, timer });
child.send({ kind: 'busyBarrier', id }, (error) => {
if (!error) return;
link.barriers.delete(id);
clearTimeout(timer);
reject(new SessionUnavailableError(`The session host could not be reached: ${error}`));
});
});
}
/** Hear every event the host at this root records from now on. */
subscribe(root: string, listener: (event: ServerEvent) => void): () => void {
const link = this.link(root);
link.subscribers.add(listener);
return () => link.subscribers.delete(listener);
}
}
/**
* Kill a session host and every process in its group. A host is started
* detached, so it leads its own group, and the provider processes it starts
* are in it too. Windows has no groups: the host's process tree goes instead.
*/
function killHostGroup(child: ChildProcess): void {
if (!child.pid) return;
if (process.platform === 'win32') {
const root = child.pid;
killProcessTree(root).catch((error: unknown) =>
console.error(`Could not stop the session host (pid ${root}): ${String(error)}`)
);
return;
}
try {
process.kill(-child.pid, 'SIGKILL');
} catch (error) {
if ((error as NodeJS.ErrnoException).code !== 'ESRCH') throw error;
}
}
export type SessionRequestHandlers = {
[K in SessionRequest['type']]: (
request: Extract<SessionRequest, { type: K }>
) => Promise<unknown>;
};
/** What the host needs of its own process to talk to its parent: `process` itself. */
export type ParentPort = {
send?: (message: unknown) => boolean;
connected: boolean;
on(event: 'message' | 'disconnect', listener: (message: unknown) => void): unknown;
off(event: 'message' | 'disconnect', listener: (message: unknown) => void): unknown;
};
/** The host's end of the pipe. */
export type ParentChannel = {
/** Answer the parent's requests with these, from now on. */
serve: (handlers: SessionRequestHandlers) => void;
/** Tell the parent requests can be sent. */
ready: () => void;
push: (event: ServerEvent) => void;
/** Say which session this host runs; again whenever that changes. */
identify: (identity: HostIdentity) => void;
/** Ask the parent, rejecting if it does not answer or goes away. */
ask: (ask: HostAsk) => Promise<unknown>;
/**
* Hear each Switch tool call the parent answered, with its result, before
* the caller does. Returns the unsubscribe.
*/
onToolAnswered: (listener: (name: string, result: unknown) => void) => () => void;
/** Say whether the session is busy, and why; `barrier` answers a `busyBarrier`. */
busy: (state: BusyState, barrier: number | null) => void;
/** Answer each `busyBarrier` with this, once it resolves. */
onBarrier: (handler: () => Promise<BusyState>) => void;
/** Take the token values the parent shares, including any sent before this was called. */
onRedactions: (handler: (values: string[]) => void) => void;
/** Stop answering requests, so the parent reads the host as going. */
close: () => void;
};
function shareRedactions(child: ChildProcess, root: string, values: string[]): void {
if (!child.connected) return;
child.send({ kind: 'redactions', values }, (error) => {
if (error)
console.warn(`Could not share token redactions with the session host at ${root}: ${error}`);
});
}
function isTokenAnswer(value: unknown): value is { kind: 'token'; token: string } {
return (
typeof value === 'object' &&
value !== null &&
(value as { kind?: unknown }).kind === 'token' &&
typeof (value as { token?: unknown }).token === 'string'
);
}
/** How long a host waits for its parent to answer; a tool call may upload files. */
const ASK_TIMEOUT_MS = 5 * 60 * 1000;
/**
* The host's end, over the IPC channel it was started with. Refuses a port
* with none: a session host is always some process's child.
*/
export function connectParent(port: ParentPort): ParentChannel {
if (!port.send)
throw new Error(
'A session host is started by its parent (Console or the agent sidecar) with an IPC channel, and this one has none.'
);
const send = (message: unknown) => {
if (port.connected) port.send!(message);
};
let handlers: SessionRequestHandlers | null = null;
let barrier: (() => Promise<BusyState>) | null = null;
let redactionHandler: ((values: string[]) => void) | null = null;
const sharedEarly: string[] = [];
let serving = true;
let nextAsk = 0;
const toolListeners = new Set<(name: string, result: unknown) => void>();
const asks = new Map<
number,
{
resolve: (value: unknown) => void;
reject: (error: Error) => void;
timer: ReturnType<typeof setTimeout>;
}
>();
const onMessage = (raw: unknown) => {
// Heard by the process's stop listener, not by the session channel.
if (isStopMessage(raw)) return;
const parsed = toChildSchema.safeParse(raw);
if (!parsed.success) {
console.warn('Ignoring an unreadable message from the parent process.');
return;
}
const message = parsed.data;
if (message.kind === 'answer') {
const pending = asks.get(message.id);
if (!pending) return;
asks.delete(message.id);
clearTimeout(pending.timer);
if (message.ok) pending.resolve(message.value);
else pending.reject(new Error(message.error ?? 'The parent refused.'));
return;
}
if (message.kind === 'redactions') {
if (redactionHandler) redactionHandler(message.values);
else sharedEarly.push(...message.values);
return;
}
if (message.kind === 'busyBarrier') {
if (!barrier) return;
barrier().then(
(state) => send({ kind: 'busy', ...state, barrier: message.id }),
(error: unknown) => console.warn(`Could not answer a busy barrier: ${String(error)}`)
);
return;
}
if (!serving) return;
const { id, request } = message;
if (!handlers) {
send({ kind: 'reply', id, ok: false, error: 'The session host is not ready yet.' });
return;
}
const handler = handlers[request.type] as (request: SessionRequest) => Promise<unknown>;
handler(request).then(
(value) => send({ kind: 'reply', id, ok: true, value }),
(error: unknown) =>
send({
kind: 'reply',
id,
ok: false,
error: error instanceof Error ? error.message : String(error),
})
);
};
const onDisconnect = () => {
for (const [id, pending] of asks) {
clearTimeout(pending.timer);
pending.reject(new Error('The parent process went away before it answered.'));
asks.delete(id);
}
};
port.on('message', onMessage);
port.on('disconnect', onDisconnect);
return {
serve: (next) => {
handlers = next;
},
ready: () => send({ kind: 'ready' }),
push: (event) => send({ kind: 'event', event }),
identify: (identity) => send({ kind: 'identity', identity }),
busy: (state, id) => send({ kind: 'busy', ...state, ...(id === null ? {} : { barrier: id }) }),
onBarrier: (handler) => {
barrier = handler;
},
onRedactions: (handler) => {
redactionHandler = handler;
if (sharedEarly.length) handler(sharedEarly.splice(0));
},
ask: (ask) => {
if (!port.connected)
return Promise.reject(new Error('The parent process is gone, so nothing can answer.'));
const id = nextAsk++;
return new Promise<unknown>((resolve, reject) => {
const timer = setTimeout(() => {
asks.delete(id);
reject(new Error('The parent process did not answer in time.'));
}, ASK_TIMEOUT_MS);
const answered = (value: unknown) => {
if (ask.type === 'tool')
for (const listener of toolListeners) {
try {
listener(ask.name, value);
} catch (error) {
console.error(`A tool-call listener failed: ${String(error)}`);
}
}
resolve(value);
};
asks.set(id, { resolve: answered, reject, timer });
send({ kind: 'ask', id, ask });
});
},
onToolAnswered: (listener) => {
toolListeners.add(listener);
return () => toolListeners.delete(listener);
},
close: () => {
serving = false;
},
};
}