Skip to content

Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.

48.2 KB
Raw Blame
import { createHash } from 'node:crypto';
import { join, resolve } from 'node:path';
import { setTimeout as delay } from 'node:timers/promises';
import { commandSchema, hasOwnActivity } from '@switch-console/shared/session-v1';
import type { Command, CommandStatus, Session, Snapshot } from '@switch-console/shared/session-v1';
import { z } from 'zod';
import type { ProviderAdapter, ProviderSessionStartInput } from '../adapter';
import { ActivityReporter, type Report } from './activity-reporter';
import { readStagedAttachment, stageAttachment, MAX_ATTACHMENT_BYTES } from './attachments';
import { cliToolsBase, pinnedBinary } from './cli-binaries';
import { HostWaker } from './handoff';
import { agentHasOwnUser } from './host-permissions';
import { Redactions } from './redaction';
import {
  followupCommandId,
  retryRefusal,
  roomControlFollowup,
  roomControlRefusal,
} from './room-control-followup';
import { SharedRoomInbox, type roomConnectionSchema } from './room-inbox';
import {
  planAttachments,
  roomCommand,
  roomFreshStartCommandId,
  roomMessageSchema,
  type RoomAttachmentSource,
} from './room-prompt';
import { type ServiceEndpointServer, startServiceEndpoint } from './service-endpoint';
import { githubRepositoryVisible } from './service-github';
import {
  CONNECTOR_APPROVAL_NOTICE,
  serviceFallbackNotice,
  ServiceNotices,
} from './service-notices';
import {
  connectParent,
  type BusyReason,
  type BusyState,
  type ParentChannel,
  type ParentPort,
} from './session-channel';
import { HostedSession } from './session-host';
import { startSessionMcp } from './session-mcp';
import { owedSessionStart, settleSessionStart, type OwedSessionStart } from './session-start';
import {
  needsGitHubHelpers,
  prepareSharedConfig,
  type SessionServices,
  type SharedHostConfig,
} from './shared-config';
import { SharedState } from './shared-state';
import {
  instructionsChangedNote,
  readToldInstructions,
  recordToldInstructions,
} from './told-instructions';
import {
  readToldRoomInstructions,
  recordToldRoomInstructions,
  roomInstructionsNote,
  roomInstructionsUnreadNote,
} from './told-room-instructions';
import { startVendorClis } from './vendor-cli';
import {
  CALL_TIMEOUT_MS,
  LIST_TIMEOUT_MS,
  startVendorServers,
  type VendorServers,
} from './vendor-mcp';

/** How long a faulted host waits for its last reports to reach Switch before it stops. */
const FINAL_REPORT_MS = 5_000;

/**
 * A session run on behalf of its agent.
 *
 * The host owns the session: its transcript, its generation (epoch) and its
 * recovery are its own and live in its state root. Switch holds none of it.
 * It is the child of whatever started it (Console for a local session, the
 * agent's sidecar for a remote one) and takes everything over that IPC
 * channel: room messages the agent's controller routed to it, commands from
 * Console, room controls and approval wakes. What it reports goes to the
 * `/agent-sessions` routes: that a new session started and how, a row per
 * turn step, the requests a person can answer, and the acknowledgement of
 * answers it has applied.
 *
 * A host with a parent parks itself after `parkAfterMs` with nothing to do:
 * it records `parked` and exits, and its parent starts it again when the
 * session is next needed. A hundred quiet sessions then cost nothing.
 */
export type SharedHostOptions = {
  root: string;
  resumeOperationId?: string;
  authenticate?: () => Promise<void>;
  agentApiUrl: string;
  token: string;
  session: Session;
  input: ProviderSessionStartInput;
  roomConnection?: z.infer<typeof roomConnectionSchema>;
  grant?: { roomId: string; messageId: string };
  /** The session continues a native conversation started outside Switch. */
  importHistory: boolean;
  /** The IPC channel to the process that started this host, or null if none did. */
  parent: ParentChannel | null;
  /** How long the host waits with nothing to do before parking; null never parks. */
  parkAfterMs: number | null;
  /**
   * The agent's own instructions as its definition stands now; null for a
   * configuration written before they were recorded apart.
   */
  instructions: string | null;
  /** The service tokens this session has been handed, scrubbed from every event it records. */
  redactions: Redactions;
  /** Its services falling back to the machine's own sign-in, shown in the session once it is up. */
  serviceNotices: ServiceNotices;
};

/** How long a session sits idle before its host parks, unless the environment says otherwise. */
const roomInstructionsAnswerSchema = z.object({ instructions: z.string() });

const PARK_AFTER_MS = 24 * 60 * 60 * 1000;

/**
 * The park timeout for this process: `SWITCH_SESSION_PARK_AFTER_MS` in
 * milliseconds, `off` to never park, or one day when unset.
 */
export function parkAfterMs(): number | null {
  const value = process.env.SWITCH_SESSION_PARK_AFTER_MS;
  if (value === undefined || value === '') return PARK_AFTER_MS;
  if (value === 'off') return null;
  const parsed = Number(value);
  if (!Number.isInteger(parsed) || parsed <= 0)
    throw new Error(
      `SWITCH_SESSION_PARK_AFTER_MS must be a positive number of milliseconds or "off", not "${value}".`
    );
  return parsed;
}

/**
 * How long a session waiting on a fresh-conversation decision keeps its host
 * busy. Past it the decision and the room messages it holds stay recorded,
 * but no longer count as busy, so the host may park.
 */
export const RESET_HOLD_MS = 15 * 60_000;

/** Whether a session waits on a reset decision, and if so whether its hold has ended. */
export type ResetHold = 'none' | 'holding' | 'ended';

/**
 * Why a session is busy, if it is: what keeps a host from parking. A session
 * that is stopped or failed with nothing left to decide is not busy. Work the provider is still doing after its turn
 * ended, such as background subagents, counts as a running turn.
 */
export function sessionBusy(
  snapshot: Snapshot,
  reset: ResetHold,
  roomsPending: number,
  backgroundWork: boolean
): BusyState {
  const reasons: BusyReason[] = [];
  const add = (kind: BusyReason['kind'], count: number) => {
    if (count > 0) reasons.push({ kind, count });
  };
  const running = snapshot.turns.filter((turn) => turn.status === 'running').length;
  add('turn_starting', snapshot.session.status === 'starting' ? 1 : 0);
  add('turn_running', running || (snapshot.session.status === 'running' || backgroundWork ? 1 : 0));
  add('approval_open', snapshot.requests.filter((request) => request.state === 'open').length);
  add('reset_waiting', reset === 'holding' ? 1 : 0);
  add('room_pending', reset === 'ended' ? 0 : roomsPending);
  return { busy: reasons.length > 0, reasons };
}

/**
 * The Switch tools that put something the agent wrote in front of a room: a
 * turn that called one of them has answered. Each posts to the room the
 * session is connected to (only `send_attachment` can name another), so a
 * call counts whichever room it reached.
 */
export const ROOM_POSTING_TOOLS = new Set([
  'post_message',
  'send_targeted_message',
  'send_attachment',
]);

/** Why a post to the room was refused, when the result is one; null for anything else. */
export function postFailure(name: string, result: unknown): string | null {
  if (!ROOM_POSTING_TOOLS.has(name)) return null;
  if (typeof result !== 'object' || result === null) return null;
  const { isError, content } = result as { isError?: unknown; content?: unknown };
  if (isError !== true) return null;
  const text = Array.isArray(content)
    ? content
        .map((part) => (part as { text?: unknown }).text)
        .filter((part): part is string => typeof part === 'string')
        .join(' ')
        .trim()
    : '';
  return text || 'Switch refused the post.';
}

/** Whether a Switch tool result is a post that landed. */
export function postedToRoom(name: string, result: unknown): boolean {
  if (!ROOM_POSTING_TOOLS.has(name)) return false;
  return (
    typeof result === 'object' &&
    result !== null &&
    (result as { isError?: unknown }).isError !== true
  );
}

class TransportError extends Error {}
class RequestError extends Error {
  constructor(
    readonly code: string,
    readonly status: number,
    message: string
  ) {
    super(message);
  }
}

/** How a room control names the session's current generation and turn. */
const CURRENT = 'current';

const approvalOutcomesSchema = z.array(
  z.object({
    sessionId: z.string(),
    requestId: z.string(),
    kind: z.enum(['approval', 'questions']),
    state: z.enum(['answered', 'expired']),
    answer: z.string().nullable(),
    // Stored as Switch took it from the platform, so its keys stay snake_case.
    answers: z
      .array(
        z.object({
          question_id: z.string(),
          selected_option_ids: z.array(z.string()),
          custom_text: z.string().nullable(),
        })
      )
      .nullable(),
    answeredBy: z.string().nullable(),
  })
);

export async function runSharedHost(
  options: SharedHostOptions,
  adapter: ProviderAdapter,
  signal: AbortSignal
): Promise<void> {
  const base = new URL(options.agentApiUrl);
  if (
    base.protocol !== 'https:' &&
    !(base.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(base.hostname))
  )
    throw new Error('Shared host credentials require HTTPS or a loopback server.');
  if (base.username || base.password || base.search || base.hash)
    throw new Error('Agent API URL must not contain credentials, a query, or a fragment.');
  if (options.session.sessionId !== options.input.sessionId)
    throw new Error('Shared host session identity mismatch.');
  const state = await SharedState.open(options);
  const stopped = new AbortController();
  const executionSignal = AbortSignal.any([signal, stopped.signal]);
  const agentId = options.session.agentId;
  const sessionPath = `/${encodeURIComponent(options.session.sessionId)}`;
  const origin = base.href.replace(/\/$/, '');
  let host: HostedSession | null = null;
  let failure: unknown = null;
  let shutdown: Promise<void> | null = null;
  let reporting: Promise<void> | null = null;
  let stopHearingTools: (() => void) | null = null;

  const callOnce = async (
    route: string,
    method: 'GET' | 'POST',
    body: unknown
  ): Promise<unknown> => {
    let response: Response;
    try {
      response = await fetch(`${origin}${route}`, {
        method,
        headers: { authorization: `Bearer ${options.token}`, 'content-type': 'application/json' },
        body: method === 'POST' ? JSON.stringify(body) : undefined,
        signal: AbortSignal.any([executionSignal, AbortSignal.timeout(5000)]),
        redirect: 'error',
      });
    } catch (error) {
      if (executionSignal.aborted) throw error;
      throw new TransportError(`Switch unavailable: ${String(error)}`);
    }
    if ([429, 500, 502, 503, 504].includes(response.status))
      throw new TransportError(`Switch unavailable (${response.status}).`);
    if (!response.ok) {
      const text = await response.text();
      let code = '';
      try {
        code = JSON.parse(text).code ?? '';
      } catch {
        /* The response may be plain text. */
      }
      throw new RequestError(
        code,
        response.status,
        `Switch refused ${route} (${response.status}): ${text}`
      );
    }
    return response.json();
  };
  /** Retried while Switch is unreachable; any answer, including a refusal, returns. */
  const agentSessions = async (path: string, method: 'GET' | 'POST', body: unknown) => {
    let disconnected = false;
    while (true) {
      executionSignal.throwIfAborted();
      try {
        const result = await callOnce(`/agent-sessions${path}`, method, body);
        if (disconnected) console.info('Connection to Switch restored.');
        return result;
      } catch (error) {
        if (!(error instanceof TransportError)) throw error;
        if (!disconnected) console.warn(error.message);
        disconnected = true;
        await delay(500, undefined, { signal: executionSignal });
      }
    }
  };
  const stopExecution = async () => {
    if (host) {
      shutdown ??= host.shutdown();
      await shutdown;
    }
  };
  const onAbort = () => {
    void stopExecution().catch((error) => {
      failure ??= error;
    });
  };
  executionSignal.addEventListener('abort', onAbort, { once: true });

  try {
    // Names this session to its parent, which makes the agent's tool calls
    // as this session: the room it connects to is its own rather than its
    // connection's, which it shares with the agent's other sessions.
    let identified = '';
    const identify = (session: { hostId: string; epoch: string }) => {
      const identity = {
        agentId,
        sessionId: options.session.sessionId,
        hostId: session.hostId,
        epoch: session.epoch,
      };
      const key = JSON.stringify(identity);
      if (key === identified) return;
      identified = key;
      options.parent?.identify(identity);
    };
    identify(options.session);
    await state.journal.append({ type: 'running' });
    // Read whether or not this session serves rooms: it is also where the
    // agent's controller hands over commands Switch relayed from Console.
    const waker = new HostWaker();
    let lastActive = performance.now();
    const active = () => {
      lastActive = performance.now();
    };
    const rooms = options.roomConnection ? await SharedRoomInbox.open(options.root) : null;
    // Room attachments fetched ahead of the command that names them, so one
    // that cannot be fetched is left out and said, rather than failing the turn.
    const roomAttachments = new Map<string, { data: Uint8Array; sha256: string }>();
    const fetchRoomAttachment = async (
      source: RoomAttachmentSource,
      bytes: number
    ): Promise<{ data: Uint8Array; sha256: string }> => {
      const url = `${origin}/agents/${encodeURIComponent(agentId)}/rooms/${encodeURIComponent(source.roomId)}/media?mxc=${encodeURIComponent(source.mxc)}`;
      const response = await fetch(url, {
        headers: { authorization: `Bearer ${options.token}` },
        signal: AbortSignal.any([executionSignal, AbortSignal.timeout(15000)]),
        redirect: 'error',
      });
      if (!response.ok || !response.body)
        throw new Error(`the room would not hand it over (${response.status})`);
      const chunks: Uint8Array[] = [];
      let size = 0;
      const reader = response.body.getReader();
      try {
        while (true) {
          const { done, value } = await reader.read();
          if (done) break;
          size += value.byteLength;
          if (size > MAX_ATTACHMENT_BYTES || size > bytes)
            throw new Error('it is larger than the room said');
          chunks.push(value);
        }
      } finally {
        await reader.cancel();
      }
      const data = Buffer.concat(chunks);
      if (data.byteLength !== bytes) throw new Error('it is not the size the room said');
      return { data, sha256: createHash('sha256').update(data).digest('hex') };
    };

    const parentChannel = options.parent;
    host = await HostedSession.start(
      options.root,
      {
        ...(parentChannel && options.roomConnection
          ? {
              replyToRoom: async (reply) => {
                await parentChannel.ask({ type: 'room-reply', ...reply });
              },
            }
          : {}),
        session: options.session,
        input: options.input,
        importHistory: options.importHistory,
        resumeOperationId: options.resumeOperationId,
        authenticate: options.authenticate,
        redactions: options.redactions,
        connectorApproval: () => options.serviceNotices.raise(CONNECTOR_APPROVAL_NOTICE),
        stageAttachments: (attachments) =>
          Promise.all(
            attachments.map((attachment) =>
              stageAttachment(options.root, attachment, async () => {
                const fetched =
                  roomAttachments.get(attachment.attachmentId) ??
                  (await readStagedAttachment(options.root, attachment));
                if (!fetched)
                  throw new Error(
                    `Attachment ${attachment.name} is not one this session was given in a room, so there is nowhere to fetch it from.`
                  );
                roomAttachments.delete(attachment.attachmentId);
                return fetched;
              })
            )
          ),
      },
      adapter
    );
    // Every Switch tool call the provider makes goes up this pipe, whatever
    // the provider calls the tool in its own transcript.
    const hosted = host;
    stopHearingTools =
      parentChannel?.onToolAnswered((name, result) => {
        if (postedToRoom(name, result)) hosted.agentPostedToRoom();
        const failure = postFailure(name, result);
        if (failure !== null) hosted.agentPostFailed(failure);
      }) ?? null;

    options.serviceNotices.attach((message) => host!.serviceFallback(message));

    // ── What the host reports ────────────────────────────────────────────────
    const reporter = await ActivityReporter.load(options.root);
    // A session first reporting here may have a long history behind it, and
    // reporting that would put cards up for requests settled long ago.
    if (reporter.fresh) await reporter.advance(host.replay(0).throughSequence);
    reporter.catchUp(host.replay(0).events.filter((event) => event.sequence <= reporter.cursor));
    let reportingUnsupported = false;
    const unsupported = (error: unknown): boolean => {
      if (!(error instanceof RequestError) || error.status !== 404 || error.code) return false;
      reportingUnsupported = true;
      console.warn(
        'This Switch server does not accept session activity or approval requests, so messaging platforms do not show what this session is doing.'
      );
      return true;
    };
    const send = async (report: Report): Promise<void> => {
      if (report.kind === 'activity')
        await agentSessions(`${sessionPath}/activity`, 'POST', report.row);
      else if (report.kind === 'approval.open')
        await agentSessions(`${sessionPath}/approvals`, 'POST', report.body);
      else
        await agentSessions(
          `${sessionPath}/approvals/${encodeURIComponent(report.requestId)}/close`,
          'POST',
          null
        );
    };
    // A server that predates usage refuses a row that carries it. The row is
    // what platforms draw, so it goes again without, and the spend is not counted.
    const sentWithoutUsage = async (item: Report, error: RequestError): Promise<boolean> => {
      if (item.kind !== 'activity' || !item.row.usage || error.status !== 422) return false;
      const { usage: _usage, ...row } = item.row;
      console.warn(
        `Switch refused the usage of turn ${row.turn_id}, so it is not counted against the workspace: ${error.message}`
      );
      await send({ kind: 'activity', row });
      return true;
    };
    // One report at a time: the loop below and the last one before a fault share the cursor.
    let reportChain: Promise<void> = Promise.resolve();
    const reportInTurn = () => (reportChain = reportChain.catch(() => {}).then(report));
    const report = async () => {
      if (reportingUnsupported) return;
      const { events } = host!.replay(reporter.cursor);
      if (!events.length) return;
      for (const event of events) {
        const reports = reporter.reports(
          event,
          (turnId) => host!.originOf(turnId),
          (turnId) => host!.usageOf(turnId)
        );
        for (const item of reports) {
          try {
            await send(item);
          } catch (error) {
            if (!(error instanceof RequestError)) throw error;
            if (unsupported(error)) return;
            if (await sentWithoutUsage(item, error)) continue;
            // A request Switch refused, or one opened before this session
            // first reported here, has nothing to close.
            if (item.kind === 'approval.close' && error.code === 'NOT_FOUND') continue;
            console.warn(
              `Switch refused ${item.kind} from session event ${event.sequence}; it is not shown on messaging platforms: ${error.message}`
            );
          }
        }
      }
      await reporter.advance(events.at(-1)!.sequence);
    };
    let outcomesCheckedAt = -Infinity;
    const applyOutcomes = async (force: boolean) => {
      if (reportingUnsupported) return;
      const woken = waker.takeApprovalWake();
      const waiting = host!.snapshot().requests.some((r) => r.state === 'open');
      // The watcher's wake is the prompt route; the interval only covers a
      // wake that was lost, and only while a person's answer is awaited.
      if (!force && !woken && !(waiting && performance.now() - outcomesCheckedAt >= 5000)) return;
      outcomesCheckedAt = performance.now();
      let listed: unknown;
      try {
        listed = await agentSessions('/approvals/outcomes', 'GET', null);
      } catch (error) {
        if (unsupported(error)) return;
        throw error;
      }
      for (const outcome of approvalOutcomesSchema.parse(listed)) {
        if (outcome.sessionId !== options.session.sessionId) continue;
        try {
          await host!.applyApprovalOutcome({
            requestId: outcome.requestId,
            kind: outcome.kind,
            state: outcome.state,
            answer: outcome.answer,
            answers:
              outcome.answers?.map((answer) => ({
                questionId: answer.question_id,
                selectedOptionIds: answer.selected_option_ids,
                customText: answer.custom_text,
              })) ?? null,
            answeredBy: outcome.answeredBy,
          });
        } catch (error) {
          if (String(error).includes('HOST_STOPPING')) throw error;
          console.error(
            `Could not apply the answer to request ${outcome.requestId}; it is settled as a provider error: ${String(error)}`
          );
        }
        await agentSessions(
          `${sessionPath}/approvals/${encodeURIComponent(outcome.requestId)}/delivered`,
          'POST',
          null
        );
      }
    };

    // ── What reaches the host ────────────────────────────────────────────────
    /**
     * A room control names the session's generation and turn as `current`:
     * Switch keeps neither, so the host puts in its own. Null for an
     * interrupt with no turn running, which has nothing to stop.
     */
    const current = (command: Command): Command | null => {
      const snapshot = host!.snapshot();
      const resolved =
        command.epoch === CURRENT ? { ...command, epoch: snapshot.session.epoch } : command;
      if (resolved.body.type !== 'turn.interrupt' || resolved.body.turnId !== CURRENT)
        return resolved;
      const running = snapshot.turns.find((turn) => turn.status === 'running');
      if (!running) return null;
      return { ...resolved, body: { ...resolved.body, turnId: running.turnId } };
    };
    // ── Rejoining the room after a room reset or compaction ─────────────────
    type Followup = Extract<(typeof state.journal.records)[number], { type: 'followup' }>;
    const followups = (): Followup[] =>
      state.journal.records.filter((record): record is Followup => record.type === 'followup');
    const followupFor = (
      command: Command,
      requesterName: string | null,
      direct: boolean
    ): Followup | null => {
      // A direct chat's reset is meant to forget the conversation; its placement survives, so nothing is owed.
      if (direct && command.body.type === 'session.reset') return null;
      const action =
        command.body.type === 'session.reset'
          ? 'reset'
          : command.body.type === 'session.compact'
            ? 'compact'
            : null;
      if (!action || !command.origin?.roomId) return null;
      return {
        type: 'followup',
        commandId: command.commandId,
        action,
        roomId: command.origin.roomId,
        threadId: command.origin.threadId,
        actorId: command.origin.actorId,
        requesterName,
        surface: command.origin.surface,
      };
    };
    /** Queues the follow-up once; a replay after a restart finds it already recorded. */
    const sendFollowup = async (owed: Followup): Promise<void> => {
      const commandId = followupCommandId(owed.commandId);
      const snapshot = host!.snapshot();
      if (snapshot.commandStatuses.some((entry) => entry.commandId === commandId)) return;
      await run(
        {
          contractVersion: 1,
          commandId,
          sessionId: options.session.sessionId,
          epoch: snapshot.session.epoch,
          origin: {
            surface: owed.surface,
            actorId: owed.actorId,
            roomId: owed.roomId,
            threadId: owed.threadId,
            messageId: null,
          },
          body: {
            type: 'message.send',
            text: roomControlFollowup(owed),
            attachments: [],
            delivery: 'queue',
          },
        },
        null,
        false
      );
    };
    /** Tells the parent whenever the session's busy state changes. */
    let announcedBusy = '';
    let resetHeldSince: number | null = null;
    const resetHold = (): ResetHold => {
      if (!host!.resetDecisionPending) {
        resetHeldSince = null;
        return 'none';
      }
      resetHeldSince ??= Date.now();
      return Date.now() - resetHeldSince < RESET_HOLD_MS ? 'holding' : 'ended';
    };
    const busyNow = (): BusyState =>
      sessionBusy(
        host!.snapshot(),
        resetHold(),
        rooms?.pending().length ?? 0,
        host!.backgroundWorkRunning
      );
    const announceBusy = () => {
      const state = busyNow();
      const key = JSON.stringify(state);
      if (key === announcedBusy) return;
      if (resetHold() === 'ended')
        console.warn(
          `Session ${options.session.sessionId} has waited ${RESET_HOLD_MS / 60_000} min for a fresh-conversation decision; it no longer keeps its host busy. The decision and its ${rooms?.pending().length ?? 0} held room message(s) are kept for when it next runs.`
        );
      announcedBusy = key;
      options.parent?.busy(state, null);
    };
    // ── Telling a running conversation its instructions changed ───────────
    // A conversation that has not started yet is given the current ones as it
    // starts. One that has, and was told others, gets a note with the next
    // room message: its provider would otherwise keep the old ones.
    // Turns copied in from a conversation started outside Switch are not this
    // conversation having started here: it resumes under Switch's context.
    const startedHere = () => hasOwnActivity(host!.snapshot());
    const instructions = options.instructions;
    let instructionsNote: string | null = null;
    if (instructions !== null) {
      const told = await readToldInstructions(options.root);
      if (!startedHere()) await recordToldInstructions(options.root, instructions);
      else if (told !== instructions) instructionsNote = instructionsChangedNote(instructions);
    }
    const instructionsTold = async (): Promise<void> => {
      if (instructions === null) return;
      await recordToldInstructions(options.root, instructions);
      instructionsNote = null;
    };
    // Where the provider takes a developer message mid-conversation, that is
    // how it hears: it outranks anything said in a user message. Otherwise
    // the note rides on the next room message.
    if (instructionsNote !== null && adapter.addDeveloperMessage)
      try {
        await adapter.addDeveloperMessage(options.session.sessionId, instructionsNote);
        await instructionsTold();
      } catch (error) {
        console.warn(
          `Could not give session ${options.session.sessionId} its changed instructions as a developer message (${error instanceof Error ? error.message : String(error)}); it is told with its next room message instead.`
        );
      }
    // ── Telling a conversation the instructions of the rooms it is in ─────
    let toldRooms = await readToldRoomInstructions(options.root);
    const roomInstructionsTold = async (rooms: Record<string, string>): Promise<void> => {
      toldRooms = rooms;
      await recordToldRoomInstructions(options.root, rooms);
    };
    /**
     * What to tell the conversation about a room's instructions before its
     * message, and the instructions to record as told once the message runs
     * (null when they could not be read, so the next message tries again).
     */
    const roomInstructionsFor = async (
      roomId: string
    ): Promise<{ note: string | null; instructions: string | null }> => {
      if (!parentChannel || !options.roomConnection) return { note: null, instructions: null };
      if (!startedHere()) toldRooms = {};
      try {
        const { instructions } = roomInstructionsAnswerSchema.parse(
          await parentChannel.ask({ type: 'room-instructions', roomId })
        );
        return {
          note: roomInstructionsNote(roomId, instructions, toldRooms[roomId]),
          instructions,
        };
      } catch (error) {
        executionSignal.throwIfAborted();
        const reason = error instanceof Error ? error.message : String(error);
        console.warn(
          `Could not read room ${roomId}'s instructions for session ${options.session.sessionId} (${reason}); the session is told to read them itself.`
        );
        return { note: roomInstructionsUnreadNote(roomId, reason), instructions: null };
      }
    };
    /** Runs a command, answering with what the host recorded for it, or why it did not run. */
    const run = async (
      value: unknown,
      requesterName: string | null,
      direct: boolean
    ): Promise<CommandStatus | string> => {
      executionSignal.throwIfAborted();
      active();
      const parsed = commandSchema.safeParse(value);
      if (!parsed.success) {
        console.warn(`Ignoring an unreadable session command: ${parsed.error.message}`);
        return `The command is not readable: ${parsed.error.message}`;
      }
      const command = current(parsed.data);
      if (!command) return 'There is no turn running to interrupt.';
      if (command.sessionId !== options.session.sessionId) {
        console.warn(`Ignoring command ${command.commandId}, which is for another session.`);
        return 'The command is for another session.';
      }
      // A command built against an earlier generation of the session was
      // about a conversation a reset or a restart has since replaced.
      if (command.epoch !== host!.snapshot().session.epoch)
        return 'STALE_EPOCH: the session has been reset or restarted since this command was made.';
      const owed = followupFor(command, requesterName, direct);
      if (owed && !followups().some((record) => record.commandId === command.commandId))
        await state.journal.append(owed);
      const repeated = host!
        .snapshot()
        .commandStatuses.some((entry) => entry.commandId === command.commandId);
      try {
        await host!.command(command);
      } catch (error) {
        await host!.reject(command, error);
      }
      const status = host!
        .snapshot()
        .commandStatuses.find((entry) => entry.commandId === command.commandId);
      if (owed && status?.status === 'applied') await sendFollowup(owed);
      // Switch already told the room the control is under way; a refusal is answered there too.
      if (
        owed &&
        status?.status === 'rejected' &&
        !repeated &&
        parentChannel &&
        options.roomConnection
      )
        void parentChannel
          .ask({
            type: 'room-reply',
            roomId: owed.roomId,
            threadId: owed.threadId,
            body: roomControlRefusal(owed.action, status.message),
          })
          .catch((error: unknown) =>
            console.warn(
              `Could not tell room ${owed.roomId} that its ${owed.action} was refused: ${String(error)}`
            )
          );
      // A retry asked for from a room that cannot run is answered there, where it was asked.
      if (
        command.body.type === 'message.retry' &&
        status?.status === 'rejected' &&
        !repeated &&
        parentChannel &&
        options.roomConnection &&
        command.origin.roomId
      )
        void parentChannel
          .ask({
            type: 'room-reply',
            roomId: command.origin.roomId,
            threadId: command.origin.threadId,
            body: retryRefusal(status.message),
          })
          .catch((error: unknown) =>
            console.warn(
              `Could not tell room ${command.origin.roomId} that its retry was refused: ${String(error)}`
            )
          );
      // A fresh conversation starts with the instructions this host was given,
      // and has been told no room's.
      if (command.body.type === 'session.reset' && status?.status === 'applied') {
        await instructionsTold();
        await roomInstructionsTold({});
      }
      return status ?? 'The host did not record the command.';
    };
    /** Turn each room message handed over into the command it amounts to, in order. */
    const admitRoomMessages = async (inbox: SharedRoomInbox): Promise<void> => {
      for (const event of inbox.pending()) {
        const message = roomMessageSchema.safeParse(event.event);
        if (!message.success) {
          await host!.notice(
            `Room message ${event.messageId} reached this session without its content, so it could not be run. Ask the sender to address the agent again.`
          );
          await inbox.acknowledge(event);
          continue;
        }
        const attachments = planAttachments({
          roomId: event.roomId,
          message: message.data,
          supportedMimeTypes: host!.snapshot().session.capabilities.attachmentMimeTypes,
        });
        for (const planned of attachments) {
          if (planned.refused !== null) continue;
          try {
            roomAttachments.set(
              planned.attachmentId,
              await fetchRoomAttachment(planned.source, planned.bytes)
            );
          } catch (error) {
            if (executionSignal.aborted) throw error;
            planned.refused = `It could not be fetched: ${error instanceof Error ? error.message : String(error)}.`;
          }
        }
        const room = await roomInstructionsFor(event.roomId);
        const preface = [instructionsNote, room.note].filter((note) => note !== null);
        const command = roomCommand({
          agentId,
          sessionId: options.session.sessionId,
          epoch: host!.snapshot().session.epoch,
          roomId: event.roomId,
          message: message.data,
          surface: 'switch-web',
          attachments,
          preface: preface.length ? preface.join('\n\n') : null,
          firstOfConversation: !startedHere(),
        });
        // Taken by the host before the delivery is acknowledged: the host's
        // inbox is durable, so a crash between the two runs the message once
        // rather than losing it.
        const outcome = await run(command, null, false);
        if (typeof outcome !== 'string' && outcome.status !== 'rejected') {
          if (instructionsNote !== null) await instructionsTold();
          if (room.instructions !== null)
            await roomInstructionsTold({ ...toldRooms, [event.roomId]: room.instructions });
        }
        await inbox.acknowledge(event);
      }
    };

    /**
     * A room message reached a conversation that cannot continue as it was —
     * its provider lost it, or a reset was cut off. Nobody in the room can
     * press "Start a fresh conversation" for it, so the session does: the
     * message would otherwise wait unseen for someone at the Console. The
     * transcript keeps everything said before.
     */
    const startFreshFor = async (event: { roomId: string; messageId: string }): Promise<void> => {
      await host!.startingFreshForRoom();
      const outcome = await run(
        {
          contractVersion: 1,
          commandId: roomFreshStartCommandId(agentId, event.roomId, event.messageId),
          sessionId: options.session.sessionId,
          epoch: host!.snapshot().session.epoch,
          origin: {
            surface: 'switch-web',
            actorId: agentId,
            roomId: null,
            threadId: null,
            messageId: null,
          },
          body: { type: 'session.reset' },
        },
        null,
        false
      );
      if (typeof outcome === 'string')
        throw new Error(`Could not start a fresh conversation for a room message: ${outcome}`);
      if (outcome.status === 'rejected' || outcome.status === 'unknown')
        throw new Error(
          `Could not start a fresh conversation for a room message: ${outcome.message ?? outcome.code ?? outcome.status}`
        );
    };

    identify(host.snapshot().session);
    // A parent that started this host talks to it over IPC: commands and room
    // messages come down the pipe, and every recorded event goes up it.
    const parent = options.parent;
    parent?.serve({
      // Busy is announced before the reply, so a parent that has the reply has
      // already heard any change the command made.
      command: async ({ command, requesterName, direct }) => {
        const outcome = await run(command, requesterName, direct === true);
        announceBusy();
        if (typeof outcome === 'string') throw new Error(outcome);
        return outcome;
      },
      room: async ({ handoff }) => {
        if (!rooms) throw new Error('This session serves no rooms.');
        await rooms.accept(handoff);
        active();
        announceBusy();
        waker.nudge();
        return { accepted: true };
      },
      snapshot: async () => host!.snapshot(),
      reasoning: async ({ turnIds }) => host!.reasoning(turnIds),
      approvals: async () => {
        active();
        waker.approvalsWaiting();
        return null;
      },
    });
    host.onPublished(active);
    host.onPublished(() => identify(host!.snapshot().session));
    if (parent) {
      host.onPublished(announceBusy);
      parent.onBarrier(async () => {
        await host!.barrier();
        return busyNow();
      });
      host.onPublished((event) => parent.push(event));
      announceBusy();
      parent.ready();
    }
    /**
     * Nothing running, nothing waiting on a person, nothing handed over, for
     * long enough. Subagents still at work after their turn ended count as
     * running, and the wait starts again from when the last of them stops.
     */
    const idleEnough = (): boolean => {
      if (!parent || options.parkAfterMs === null) return false;
      if (host!.backgroundWorkRunning) {
        active();
        return false;
      }
      if (performance.now() - lastActive < options.parkAfterMs) return false;
      return host!.snapshot().session.status === 'ready' && !busyNow().busy;
    };
    for (const owed of followups()) {
      const applied = host
        .snapshot()
        .commandStatuses.some(
          (entry) => entry.commandId === owed.commandId && entry.status === 'applied'
        );
      if (applied) await sendFollowup(owed);
    }
    /**
     * Tells the server, once, that this session is new and how it started —
     * what its launcher recorded when it created the state root. Owed until
     * the server answers, so a host stopped before then reports it next time;
     * the server counts a repeat once.
     *
     * Its own failures stay its own. A server that predates the route answers
     * a bare 404, which says nothing about the activity routes, so it is not
     * taken as the `unsupported` that switches all reporting off.
     */
    const reportStart = async (): Promise<void> => {
      try {
        let owed: OwedSessionStart | 'unreadable' | null;
        try {
          owed = await owedSessionStart(options.root);
        } catch (error) {
          console.warn(
            `Could not read how this session started, so it is not reported: ${String(error)}`
          );
          owed = 'unreadable';
        }
        if (owed === null) return;
        if (owed !== 'unreadable') {
          try {
            await agentSessions(`${sessionPath}/started`, 'POST', { start_source: owed });
          } catch (error) {
            if (!(error instanceof RequestError)) throw error;
            if (error.status === 404 && !error.code)
              console.warn(
                'This Switch server does not accept session start reports, so how this session started is not reported.'
              );
            else console.warn(`Switch refused this session's start report: ${error.message}`);
          }
        }
        await settleSessionStart(options.root);
      } catch (error) {
        // Stopping is the one reason to let go: whatever is still owed is
        // reported the next time this session's host runs.
        if (executionSignal.aborted) throw error;
        console.warn(`Could not report how this session started: ${String(error)}`);
      }
    };
    // Reporting runs beside the session rather than in its way: while Switch
    // is unreachable the reports wait and retry, and the session keeps working.
    let reportingFailure: unknown = null;
    reporting = (async () => {
      await reportStart();
      let force = true;
      while (!executionSignal.aborted) {
        await reportInTurn();
        await applyOutcomes(force);
        force = false;
        await waker.idleReporting(250, executionSignal);
      }
    })().catch((error: unknown) => {
      if (!executionSignal.aborted) reportingFailure = error;
    });
    let heldForDecision = false;
    while (!executionSignal.aborted) {
      if (reportingFailure) throw reportingFailure;
      const status = host.snapshot().session.status;
      if (status === 'stopped') break;
      if (status === 'error' && !host.resetDecisionPending) {
        // What faulted it, and the turn that ended with it, are what Switch most
        // needs to show; stopping would drop them unreported, the turn left running.
        await Promise.race([
          reportInTurn().catch((error: unknown) =>
            console.warn(`Could not report this session's last events: ${String(error)}`)
          ),
          delay(FINAL_REPORT_MS, undefined, { signal: executionSignal }).catch(() => {}),
        ]);
        throw new Error(
          'HOST_FAULTED: Provider execution failed. Inspect the transcript before recovery.'
        );
      }
      if (host.resetDecisionPending) {
        heldForDecision = true;
        const first = rooms?.pending()[0];
        if (first) await startFreshFor(first);
      } else if (heldForDecision) {
        heldForDecision = false;
        const held = rooms?.pending().length ?? 0;
        if (held) await host.roomBacklogDelivered(held);
      }
      if (rooms && ['ready', 'running'].includes(status)) await admitRoomMessages(rooms);
      announceBusy();
      if (idleEnough()) {
        console.info(
          `Parking session ${options.session.sessionId} after ${Math.round(options.parkAfterMs! / 1000)} s idle.`
        );
        // Stops answering first: a request that arrives now waits for the
        // exit, which the parent reads as the host being gone and starts it again.
        parent?.close();
        await state.journal.append({ type: 'parked' });
        break;
      }
      await waker.idle(250, executionSignal);
    }
  } catch (error) {
    if (!signal.aborted) failure ??= error;
  } finally {
    stopHearingTools?.();
    stopped.abort();
    await reporting;
    try {
      await stopExecution();
      await state.journal.append({ type: 'quiesced' });
    } catch (error) {
      if (failure)
        console.warn('Shared host cleanup failed after an earlier error:', String(error));
      failure ??= error;
    }
    executionSignal.removeEventListener('abort', onAbort);
  }
  if (failure) throw failure;
}

/**
 * A session host as its own process: the child of Console or the agent's
 * sidecar, which it reaches over `port`.
 *
 * The Switch tools are served on loopback before the provider starts, so the
 * CLI is launched already pointing at them; every call goes up the pipe to
 * the parent. `authenticate` checks the provider's own sign-in with the
 * environment the CLI will get, where there is one to check.
 */
export async function hostSessionProcess(input: {
  root: string;
  config: SharedHostConfig;
  adapter: ProviderAdapter;
  port: ParentPort;
  authenticate: ((input: ProviderSessionStartInput) => Promise<void>) | null;
  /** The agent's service grants, as this session starts. */
  services: SessionServices;
  /**
   * What the session is told about services that went or came since its
   * previous host (`servicesChangeSince`); null for nothing.
   */
  servicesChange: string | null;
  /** This host's bundle, which the session's service helpers run from. */
  entrypoint: string;
  signal: AbortSignal;
}): Promise<void> {
  const { config } = input;
  const parent = connectParent(input.port);
  const mcp = await startSessionMcp(parent);
  const redactions = new Redactions();
  parent.onRedactions((values) => redactions.addListed(values));
  const serviceNotices = new ServiceNotices();
  // An agent run as a user of its own has no sign-in of the owner's to fall back to.
  const fallback = !agentHasOwnUser();
  let endpoint: ServiceEndpointServer | null = null;
  let vendors: VendorServers | null = null;
  let clis: VendorServers | null = null;
  try {
    const { grants, unavailable } = input.services;
    vendors = await startVendorServers({
      grants,
      ask: parent.ask,
      redactions,
      listTimeoutMs: LIST_TIMEOUT_MS,
      callTimeoutMs: CALL_TIMEOUT_MS,
      fetch,
    });
    clis = await startVendorClis({
      grants,
      ask: parent.ask,
      redactions,
      cwd: config.start.input.cwd,
      stateDir: join(input.root, 'service-cli'),
      binary: pinnedBinary({
        base: cliToolsBase(),
        platform: process.platform,
        arch: process.arch,
        fetch,
        tar: 'tar',
      }),
      hostEnv: process.env,
      platform: process.platform,
    });
    for (const name of Object.keys(clis.specs))
      if (name in vendors.specs) throw new Error(`Two granted services' tools are named ${name}.`);
    if (unavailable !== null)
      serviceNotices.raise(
        serviceFallbackNotice('github', `its grants could not be read: ${unavailable}`, fallback)
      );
    if (needsGitHubHelpers(input.services)) {
      if (process.platform === 'win32')
        serviceNotices.raise(
          serviceFallbackNotice('github', "Switch's GitHub helpers do not run on Windows yet", true)
        );
      else
        endpoint = await startServiceEndpoint({
          services: grants.map((grant) => grant.service),
          unavailable,
          ask: parent.ask,
          redactions,
          notices: serviceNotices,
          fallback,
          repositoryVisible: githubRepositoryVisible,
          now: Date.now,
        });
    }
    const prepared = await prepareSharedConfig(
      input.root,
      config,
      mcp.spec,
      input.services,
      endpoint && { endpoint, execPath: process.execPath, entrypoint: input.entrypoint },
      { ...vendors.specs, ...clis.specs },
      (secret) => redactions.add(secret)
    );
    for (const notice of prepared.notices) serviceNotices.raise(notice);
    // The people watching see it as a notice; the agent reads it with the
    // context it resumes under, so it does not go looking for tools it no
    // longer has.
    if (input.servicesChange !== null) {
      serviceNotices.raise(input.servicesChange);
      prepared.input.systemContext = [prepared.input.systemContext, input.servicesChange]
        .filter(Boolean)
        .join('\n\n');
    }
    const authenticate = input.authenticate;
    await runSharedHost(
      {
        root: resolve(input.root),
        agentApiUrl: prepared.agentApiUrl,
        token: prepared.token,
        session: config.session,
        resumeOperationId: config.resumeOperationId,
        ...(authenticate ? { authenticate: () => authenticate(prepared.input) } : {}),
        input: prepared.input,
        roomConnection: config.roomConnection,
        grant: config.grant,
        importHistory: config.importHistory ?? false,
        parent,
        parkAfterMs: parkAfterMs(),
        instructions: config.execution?.instructions ?? null,
        redactions,
        serviceNotices,
      },
      input.adapter,
      input.signal
    );
  } finally {
    await clis?.close();
    await vendors?.close();
    await endpoint?.close();
    await mcp.close();
  }
}