pim-agent 0.0.1 → 0.10.0

package/packages/server/src/WsGateway.ts

@@ -0,0 +1,798 @@
+import type { Server, ServerWebSocket } from "bun";
+
+import type { ImageContent } from "@earendil-works/pi-ai";
+import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
+
+import { Attachments } from "#core/attachments/Attachments";
+import type { PickerItem } from "#core/picker/PickerItem";
+import { Directories } from "#core/shared/Directories";
+import type { DirectoryListing } from "#core/shared/Directories";
+import { Git, type GitBranch } from "#core/shared/Git";
+import { GitMonitor, type GitRun } from "#core/shared/GitMonitor";
+import { RepoDiff } from "#core/shared/RepoDiff";
+import { ReadCursors } from "#core/session/ReadCursors";
+import type { SessionHost } from "#core/session/SessionHost";
+import { SessionMeta } from "#core/session/SessionMeta";
+import type { SessionRegistry } from "#core/session/SessionRegistry";
+import { PimVersion } from "#core/shared/PimVersion";
+import { SubagentLogs } from "#core/shared/SubagentLogs";
+import type { UpdateOutcome } from "#core/shared/Updater";
+import type { Command } from "#protocol/Command";
+import type { ChangeList, FileDiff, FileLines } from "#protocol/Diff";
+import type {
+  ModelView,
+  ProjectView,
+  SearchHitView,
+  ServerEvent,
+  SessionSummaryView,
+} from "#protocol/ServerEvent";
+import { ClientConnection } from "./ClientConnection";
+import { Reloader } from "./Reloader";
+import { SessionCatalogue } from "./SessionCatalogue";
+import { SessionProjection } from "./SessionProjection";
+import { SessionStream } from "./SessionStream";
+import { StaticClient } from "./StaticClient";
+import { AttachmentEndpoint } from "./AttachmentEndpoint";
+import { ImageEndpoint } from "./ImageEndpoint";
+
+export type WsGatewayDeps = {
+  readonly registry: SessionRegistry;
+  /** Loopback by default and never `0.0.0.0`: full host access, no auth. */
+  readonly hostname?: string;
+  /** 0 asks the OS for a free port; read it back from `port`. */
+  readonly port?: number;
+  /** Where uploaded bytes are kept; defaults to `~/.pim/attachments`. */
+  readonly attachmentsRoot?: string;
+  /** Where `read` spilled the pictures it showed the model; defaults to `~/.pim/cache`. */
+  readonly imagesRoot?: string;
+  /** Where the read cursors live; defaults to `~/.pim/read.json`. */
+  readonly readCursorsPath?: string;
+  /** Where the per-session and per-project overrides live; defaults to `~/.pim/sessions.json`. */
+  readonly sessionMetaPath?: string;
+  /** How often a session file is polled where `fs.watch` says nothing; the default is a second. */
+  readonly pollMs?: number;
+  /** The built web client; defaults to the bundle shipped beside this package. */
+  readonly clientDir?: string;
+  /** Runs the update a `reload` asks for, reporting each step as it starts. */
+  readonly update?: (onStep: (label: string) => void) => Promise<UpdateOutcome>;
+  /** Ends this process so the supervisor replaces it with the updated code. */
+  readonly shutdown?: () => Promise<void>;
+};
+
+type Outcome = {
+  readonly error?: string;
+  readonly items?: readonly PickerItem[];
+  readonly sessions?: readonly SessionSummaryView[];
+  readonly projects?: readonly ProjectView[];
+  readonly hits?: readonly SearchHitView[];
+  readonly dropped?: readonly string[];
+  readonly scanned?: number;
+  readonly models?: readonly ModelView[];
+  readonly thinkingLevels?: readonly string[];
+  readonly directory?: DirectoryListing;
+  readonly branches?: readonly GitBranch[];
+  readonly commit?: { readonly sha: string };
+  readonly changes?: ChangeList;
+  readonly fileDiff?: FileDiff;
+  readonly fileLines?: FileLines;
+  readonly restored?: readonly string[];
+  readonly after?: () => void;
+};
+
+type StreamTarget = {
+  readonly sessionId?: string;
+  readonly cwd?: string;
+  readonly like?: SessionHost;
+};
+
+export const DEFAULT_PORT = 4319;
+
+export const DEFAULT_HOSTNAME = "127.0.0.1";
+
+// Bun 1.3.14 never frees the slot of a server-closed socket, so an unbounded `Server.stop(true)` hangs.
+const STOP_GRACE_MS = 250;
+
+/** The transport half of pim-server: a WebSocket endpoint over the session runtime in `core`. */
+export class WsGateway {
+  private readonly registry: SessionRegistry;
+  private readonly hostname: string;
+  private readonly requestedPort: number;
+  private readonly uploads: AttachmentEndpoint;
+  private readonly images: ImageEndpoint;
+  private readonly catalogue: SessionCatalogue;
+  private readonly meta: SessionMeta;
+  private readonly client: StaticClient;
+  private readonly streams = new Map<string, SessionStream>();
+  private readonly opening = new Map<string, Promise<SessionStream>>();
+  private readonly connections = new Map<
+    ServerWebSocket<undefined>,
+    ClientConnection
+  >();
+  private readonly reloader: Reloader;
+  private readonly git = new GitMonitor();
+  private readonly pollMs: number | undefined;
+  private readonly busyRepos = new Set<string>();
+  private versionsRead: Promise<readonly [string, string]> | undefined;
+  private server: Server<undefined> | undefined;
+
+  public constructor(deps: WsGatewayDeps) {
+    this.registry = deps.registry;
+    this.hostname = deps.hostname ?? DEFAULT_HOSTNAME;
+    this.requestedPort = deps.port ?? DEFAULT_PORT;
+    this.pollMs = deps.pollMs;
+    this.uploads = new AttachmentEndpoint(
+      deps.attachmentsRoot === undefined ? {} : { root: deps.attachmentsRoot }
+    );
+    this.images = new ImageEndpoint(
+      deps.imagesRoot === undefined ? {} : { root: deps.imagesRoot }
+    );
+    this.meta = new SessionMeta(deps.sessionMetaPath);
+    this.catalogue = new SessionCatalogue({
+      registry: deps.registry,
+      cursors: new ReadCursors(deps.readCursorsPath),
+      meta: this.meta,
+      liveStatus: (sessionId) => this.streams.get(sessionId)?.host.status,
+      liveSessionIds: () => this.streams.keys(),
+      isBeingRead: (sessionId) => this.isBeingRead(sessionId),
+      announce: (event) => {
+        this.broadcast(event);
+      },
+    });
+    this.client = new StaticClient(deps.clientDir);
+    this.reloader = new Reloader({
+      announce: (event) => {
+        this.broadcast(event);
+      },
+      update: deps.update,
+      shutdown: deps.shutdown,
+    });
+  }
+
+  public get port(): number {
+    const port = this.server?.port;
+    if (port === undefined) {
+      throw new Error("WsGateway is not listening");
+    }
+    return port;
+  }
+
+  public get url(): string {
+    return `ws://${this.hostname}:${this.port}`;
+  }
+
+  public start(): void {
+    if (this.server) {
+      return;
+    }
+    this.server = Bun.serve({
+      hostname: this.hostname,
+      port: this.requestedPort,
+      idleTimeout: 0,
+      fetch: (req, server) => {
+        const { pathname } = new URL(req.url);
+        if (pathname === "/health") {
+          return this.versions().then(([pimVersion]) =>
+            Response.json({ ok: true, pimVersion })
+          );
+        }
+        if (AttachmentEndpoint.owns(pathname)) {
+          return this.uploads.handle(req);
+        }
+        if (ImageEndpoint.owns(pathname)) {
+          return this.images.handle(req);
+        }
+        // Try the upgrade first: the socket must answer on every path.
+        return server.upgrade(req) ? undefined : this.client.handle(req);
+      },
+      websocket: {
+        backpressureLimit: 8 << 20,
+        closeOnBackpressureLimit: false,
+        // Dedicated, so the window survives between frames: the repeated event envelope is most of a delta.
+        perMessageDeflate: { compress: "dedicated", decompress: "dedicated" },
+        open: (ws) => {
+          this.connections.set(ws, new ClientConnection(ws));
+          this.syncWatches();
+        },
+        message: (ws, raw) => {
+          void this.onMessage(ws, raw);
+        },
+        drain: (ws) => {
+          this.connections.get(ws)?.onDrain();
+        },
+        close: (ws) => {
+          this.connections.get(ws)?.close();
+          this.connections.delete(ws);
+          this.syncWatches();
+        },
+      },
+    });
+  }
+
+  public async stop(): Promise<void> {
+    for (const stream of this.streams.values()) {
+      stream.dispose();
+    }
+    this.streams.clear();
+    this.opening.clear();
+    this.git.dispose();
+    this.busyRepos.clear();
+    this.catalogue.watch(false);
+    this.catalogue.clear();
+    await this.catalogue.flush();
+    for (const connection of this.connections.values()) {
+      connection.close();
+    }
+    this.connections.clear();
+    const server = this.server;
+    this.server = undefined;
+    if (server) {
+      await Promise.race([server.stop(true), Bun.sleep(STOP_GRACE_MS)]);
+    }
+  }
+
+  private async onMessage(
+    ws: ServerWebSocket<undefined>,
+    raw: string | Buffer
+  ): Promise<void> {
+    const connection = this.connections.get(ws);
+    if (!connection) {
+      return;
+    }
+    let command: Command;
+    try {
+      command = JSON.parse(String(raw)) as Command;
+    } catch {
+      connection.send({ type: "error", message: "malformed frame" });
+      return;
+    }
+    if (typeof command?.id !== "string" || typeof command?.type !== "string") {
+      connection.send({ type: "error", message: "frame is not a command" });
+      return;
+    }
+    try {
+      const { error, after, ...answer } = await this.dispatch(
+        connection,
+        command
+      );
+      connection.send({
+        type: "response",
+        id: command.id,
+        success: error === undefined,
+        ...(error === undefined ? {} : { error }),
+        ...answer,
+      });
+      after?.();
+    } catch (err) {
+      connection.send({
+        type: "response",
+        id: command.id,
+        success: false,
+        error: (err as Error).message ?? String(err),
+      });
+    }
+  }
+
+  private async dispatch(
+    connection: ClientConnection,
+    command: Command
+  ): Promise<Outcome> {
+    switch (command.type) {
+      case "attach":
+        return await this.attach(connection, command);
+      case "attention": {
+        const regained = command.value && !connection.attentive;
+        connection.setAttentive(command.value);
+        const sessionId = connection.sessionId;
+        if (regained && sessionId !== undefined) {
+          await this.catalogue.markRead(sessionId);
+        }
+        return {};
+      }
+      case "list_sessions":
+        return await this.catalogue.list(command);
+      case "search_sessions":
+        return await this.catalogue.search(command);
+      // The four below take a session this server may never have opened: a row
+      // is archived or renamed from the sidebar without being attached to, so
+      // none of them may reach for a stream. A sidecar write moves no session
+      // file and produces no `sessions_changed`, so the broadcast each ends
+      // with is the only word a listing already in a client's hands gets.
+      case "set_session_name": {
+        const name = await this.registry.setName(
+          command.sessionId,
+          command.value
+        );
+        this.broadcast({
+          type: "session_meta",
+          sessionId: command.sessionId,
+          name: name ?? null,
+        });
+        return {};
+      }
+      case "set_session_archived":
+        await this.meta.setArchived(command.sessionId, command.value);
+        this.broadcast({
+          type: "session_meta",
+          sessionId: command.sessionId,
+          archived: command.value,
+        });
+        return {};
+      case "set_session_unread":
+        await this.meta.setUnread(command.sessionId, command.value);
+        this.broadcast({
+          type: "session_meta",
+          sessionId: command.sessionId,
+          unread: command.value,
+        });
+        return {};
+      case "set_project_pinned":
+        await this.meta.setPinned(command.cwd, command.value);
+        this.broadcast({
+          type: "project_meta",
+          cwd: command.cwd,
+          pinned: command.value,
+        });
+        // The flag and the place it takes are one fact to a sidebar; a pin
+        // that arrived without a rank would sort by nothing until the next listing.
+        this.broadcast({ type: "pins_changed", order: await this.meta.pins() });
+        return {};
+      case "set_project_expanded":
+        await this.meta.setExpanded(command.cwd, command.value);
+        this.broadcast({
+          type: "project_meta",
+          cwd: command.cwd,
+          expanded: command.value,
+        });
+        return {};
+      case "set_project_label":
+        await this.meta.setLabel(command.cwd, command.value);
+        this.broadcast({
+          type: "project_meta",
+          cwd: command.cwd,
+          label: command.value,
+        });
+        return {};
+      case "set_pin_order":
+        await this.meta.setPinOrder(command.order);
+        this.broadcast({ type: "pins_changed", order: await this.meta.pins() });
+        return {};
+      case "list_models":
+        return {
+          models: this.registry.models(),
+          thinkingLevels:
+            this.streamFor(connection)?.host.supportedThinkingLevels ?? [],
+        };
+      case "list_dirs":
+        return { directory: await Directories.list(command.path) };
+      case "refresh_git": {
+        const stream = this.requireStream(connection);
+        await stream.refreshGit(command.fetch === true);
+        return {};
+      }
+      case "list_branches":
+        return {
+          branches: await Git.listBranches(
+            this.requireStream(connection).host.cwd
+          ),
+        };
+      // Reading the repository never moves it, so neither of these takes the `repoBusy` refusal.
+      case "list_changes":
+        return {
+          changes: await RepoDiff.listChanges(
+            this.requireStream(connection).host.cwd,
+            command.base,
+            this.git
+          ),
+        };
+      case "file_diff":
+        return {
+          fileDiff: await RepoDiff.fileDiff(
+            this.requireStream(connection).host.cwd,
+            command.base,
+            command.path,
+            this.git,
+            command.context
+          ),
+        };
+      case "read_lines":
+        return {
+          fileLines: await RepoDiff.readLines(
+            this.requireStream(connection).host.cwd,
+            command.base,
+            command.path,
+            command.spans,
+            this.git
+          ),
+        };
+      case "checkout": {
+        const stream = this.requireStream(connection);
+        return await this.runGit(stream, true, (cwd) =>
+          Git.checkout(cwd, command.branch)
+        );
+      }
+      case "commit":
+        return await this.commit(this.requireStream(connection), command);
+      case "pull":
+      case "push":
+        return await this.runGit(
+          this.requireStream(connection),
+          command.type === "pull",
+          command.type === "pull" ? Git.pull : Git.push
+        );
+      case "unwatch_subagent":
+        connection.unwatchSubagent(command.callId);
+        return {};
+      case "reload":
+        return this.reload(command.force === true);
+      case "user_message":
+        this.promptWithAttachments(this.requireStream(connection), command);
+        return {};
+      case "cancel": {
+        const { cancelled, restored } =
+          await this.requireStream(connection).host.cancel();
+        return cancelled ? { restored } : { error: "nothing to cancel" };
+      }
+      case "dequeue":
+        return { restored: this.requireStream(connection).host.takeBack() };
+      case "set_cwd": {
+        const stream = this.requireStream(connection);
+        const result = await stream.host.setCwd(command.value);
+        stream.syncGit();
+        stream.push(stream.sessionState());
+        if (!result.ok) {
+          return { error: result.error };
+        }
+        stream.invalidatePickers("all");
+        return {};
+      }
+      case "set_model": {
+        const stream = this.requireStream(connection);
+        const result = await stream.host.setModel(command.value);
+        stream.push(stream.sessionState());
+        return result.ok
+          ? {}
+          : {
+              error: `${result.kind} model "${command.value}"; candidates: ${result.candidates.join(", ")}`,
+            };
+      }
+      case "set_thinking": {
+        const stream = this.requireStream(connection);
+        await stream.host.setThinkingLevel(command.value as ThinkingLevel);
+        stream.push(stream.sessionState());
+        return {};
+      }
+      case "pick_files":
+        return {
+          items: await this.requireStream(connection).picker.files(
+            command.query,
+            command.limit
+          ),
+        };
+      case "pick_commands":
+        return {
+          items: this.requireStream(connection).picker.commands(
+            command.query,
+            command.limit
+          ),
+        };
+      case "watch_subagent":
+        return await this.watchSubagent(
+          connection,
+          this.requireStream(connection),
+          command
+        );
+      default:
+        this.requireStream(connection);
+        return { error: `unknown command: ${(command as Command).type}` };
+    }
+  }
+
+  private streamFor(connection: ClientConnection): SessionStream | undefined {
+    const sessionId = connection.sessionId;
+    return sessionId ? this.streams.get(sessionId) : undefined;
+  }
+
+  private requireStream(connection: ClientConnection): SessionStream {
+    const stream = this.streamFor(connection);
+    if (!stream) {
+      throw new Error("not attached: send `attach` first");
+    }
+    return stream;
+  }
+
+  // Derive the log path from the parent session and call id: a client-sent path reads arbitrary JSONL off this machine.
+  private async watchSubagent(
+    connection: ClientConnection,
+    stream: SessionStream,
+    command: Command & { readonly type: "watch_subagent" }
+  ): Promise<Outcome> {
+    if (command.sessionId !== stream.sessionId) {
+      return {
+        error: `not attached to session ${command.sessionId}; a watch reads a child of the attached session only`,
+      };
+    }
+    const path = SubagentLogs.pathFor(stream.sessionId, command.callId);
+    if (path === null) {
+      return { error: `malformed call id: ${command.callId}` };
+    }
+    // A running call may not have written its log yet; the watch waits for it.
+    if (!stream.isRunning(command.callId) && !(await Bun.file(path).exists())) {
+      return { error: `no subagent log for call ${command.callId}` };
+    }
+    await connection.watchSubagent(
+      command.callId,
+      new SessionProjection(path, () => stream.host.cwd),
+      command.fromSeq
+    );
+    return {};
+  }
+
+  private async attach(
+    connection: ClientConnection,
+    command: Command & { readonly type: "attach" }
+  ): Promise<Outcome> {
+    const attentive = command.attentive !== false;
+    const like =
+      command.like === undefined
+        ? undefined
+        : this.streams.get(command.like)?.host;
+    const [stream, [pimVersion, piVersion]] = await Promise.all([
+      this.ensureStream({
+        ...(command.sessionId === undefined
+          ? {}
+          : { sessionId: command.sessionId }),
+        ...(command.cwd === undefined ? {} : { cwd: command.cwd }),
+        ...(like === undefined ? {} : { like }),
+      }),
+      this.versions(),
+    ]);
+    connection.send({
+      type: "attached",
+      sessionId: stream.sessionId,
+      cwd: stream.host.cwd,
+      head: await stream.refresh(),
+      pimVersion,
+      piVersion,
+    });
+    await connection.attach(stream, command.fromSeq, attentive);
+    this.syncWatches();
+    if (attentive) {
+      await this.catalogue.markRead(stream.sessionId);
+    }
+    return {};
+  }
+
+  /** A watch costs a poll, so only attached sessions get one — and the catalogue only while someone is connected. */
+  private syncWatches(): void {
+    for (const [sessionId, stream] of this.streams) {
+      // Attachment, not attention: a hidden tab that lost its watches would stop hearing about the session.
+      stream.watchFiles(this.isAttached(sessionId));
+    }
+    this.catalogue.watch(this.connections.size > 0);
+  }
+
+  /**
+   * An operation that moves the working tree cannot run under an agent that
+   * may be halfway through an edit; `push` leaves the tree alone, so it can.
+   */
+  private async runGit<T = never>(
+    stream: SessionStream,
+    movesTree: boolean,
+    operation: (cwd: string) => Promise<GitRun<T>>
+  ): Promise<Outcome & { readonly value?: T }> {
+    const cwd = stream.host.cwd;
+    if (movesTree && this.repoBusy(cwd)) {
+      return {
+        error: `an agent is working in ${cwd}; wait for its turn to end`,
+      };
+    }
+    const result = await this.git.run<T>(cwd, () => operation(cwd));
+    if (!result.ok) {
+      return { error: result.error };
+    }
+    return result.value === undefined ? {} : { value: result.value };
+  }
+
+  private async commit(
+    stream: SessionStream,
+    command: Command & { readonly type: "commit" }
+  ): Promise<Outcome> {
+    const { value, ...outcome } = await this.runGit<string>(
+      stream,
+      true,
+      async (cwd) => {
+        const result = await Git.commit(cwd, {
+          message: command.message,
+          paths: command.paths,
+        });
+        return result.ok
+          ? { ok: true, value: result.sha }
+          : { ok: false, error: result.error };
+      }
+    );
+    return value === undefined ? outcome : { commit: { sha: value } };
+  }
+
+  private repoBusy(cwd: string): boolean {
+    for (const stream of this.streams.values()) {
+      if (stream.host.cwd === cwd && stream.host.status !== "idle") {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /** A turn starting anywhere freezes the branch menu of every session beside it, which only their own state can say. */
+  private syncRepoBusy(cwd: string, source: string): void {
+    const busy = this.repoBusy(cwd);
+    if (this.busyRepos.has(cwd) === busy) {
+      return;
+    }
+    if (busy) {
+      this.busyRepos.add(cwd);
+    } else {
+      this.busyRepos.delete(cwd);
+    }
+    for (const [sessionId, stream] of this.streams) {
+      if (sessionId !== source && stream.host.cwd === cwd) {
+        stream.push(stream.sessionState());
+      }
+    }
+  }
+
+  private reload(force: boolean): Outcome {
+    const busy = [...this.streams.values()]
+      .filter((stream) => stream.host.status !== "idle")
+      .map((stream) => stream.sessionId);
+    if (!force && busy.length > 0) {
+      const many = busy.length > 1;
+      return {
+        error: `${many ? "sessions" : "session"} ${busy.join(", ")} ${many ? "are" : "is"} mid-turn; reloading would kill ${many ? "those turns" : "that turn"}. Send \`reload\` with \`force\` to do it anyway`,
+      };
+    }
+    return {
+      after: () => {
+        void this.reloader.start();
+      },
+    };
+  }
+
+  private versions(): Promise<readonly [string, string]> {
+    this.versionsRead ??= Promise.all([PimVersion.current(), PimVersion.pi()]);
+    return this.versionsRead;
+  }
+
+  private isAttached(sessionId: string): boolean {
+    return this.connections
+      .values()
+      .some((connection) => connection.sessionId === sessionId);
+  }
+
+  // The TUI never attaches, so reading a session there clears no dot here and a turn it runs trips no mark.
+  private isBeingRead(sessionId: string): boolean {
+    return this.connections
+      .values()
+      .some(
+        (connection) =>
+          connection.sessionId === sessionId && connection.attentive
+      );
+  }
+
+  private broadcast(event: ServerEvent): void {
+    for (const connection of this.connections.values()) {
+      connection.send(event);
+    }
+  }
+
+  private async ensureStream(target: StreamTarget): Promise<SessionStream> {
+    const sessionId = target.sessionId;
+    if (sessionId) {
+      const live = this.streams.get(sessionId);
+      if (live) {
+        return live;
+      }
+      const pending = this.opening.get(sessionId);
+      if (pending) {
+        return await pending;
+      }
+    }
+    const build = this.buildStream(target);
+    if (sessionId) {
+      this.opening.set(sessionId, build);
+    }
+    try {
+      return await build;
+    } finally {
+      if (sessionId) {
+        this.opening.delete(sessionId);
+      }
+    }
+  }
+
+  private async buildStream(target: StreamTarget): Promise<SessionStream> {
+    const sessionId = target.sessionId;
+    const host = sessionId
+      ? await this.registry.open(sessionId)
+      : await this.registry.create({
+          ...(target.cwd === undefined ? {} : { cwd: target.cwd }),
+          ...(target.like === undefined ? {} : { like: target.like }),
+        });
+    // Pi assigns the id and the session file only once an agent exists.
+    const agent = host.agentSession ?? (await host.ensureAgent());
+    const id = agent.sessionId;
+    const path = agent.sessionFile ?? host.settings.sessionPath;
+    if (!path) {
+      throw new Error(`session ${sessionId ?? "(new)"} has no agent`);
+    }
+    const existing = this.streams.get(id);
+    if (existing) {
+      return existing;
+    }
+    const stream = new SessionStream(id, host, path, {
+      git: this.git,
+      repoBusy: () => this.repoBusy(host.cwd),
+      pollMs: this.pollMs,
+    });
+    stream.start();
+    this.catalogue.track(id, host.status);
+    stream.subscribe((event) => {
+      if (event.type === "session_state") {
+        this.catalogue.onStatus(id, event.status);
+        this.syncRepoBusy(stream.host.cwd, id);
+      }
+    });
+    this.streams.set(id, stream);
+    return stream;
+  }
+
+  private promptWithAttachments(
+    stream: SessionStream,
+    command: Command & { readonly type: "user_message" }
+  ): void {
+    const taken = this.uploads.take(
+      stream.sessionId,
+      (command.attachments ?? []).map((ref) => ref.id)
+    );
+    const { lines, images } = Attachments.render(taken);
+    const text = [command.text, ...lines].filter(Boolean).join("\n\n").trim();
+    this.prompt(stream, text, images);
+  }
+
+  // Merge into the queued message: pi holds at most one, so a second queued send would be unreachable.
+  private prompt(
+    stream: SessionStream,
+    text: string,
+    images: readonly ImageContent[] = []
+  ): void {
+    const attached = images.length === 0 ? {} : { images: [...images] };
+    const host = stream.host;
+    const agent = host.agentSession;
+    const failed = (err: unknown, what: string): void => {
+      console.error(`[gateway] ${what} failed:`, err);
+      stream.push({
+        type: "error",
+        message: (err as Error).message || String(err),
+      });
+    };
+    if (agent && host.isStreaming) {
+      const queued = [...host.takeBack(), text].join("\n\n");
+      void agent
+        .prompt(queued, {
+          streamingBehavior: "steer",
+          source: "rpc",
+          ...attached,
+        })
+        .catch((err: unknown) => {
+          failed(err, "steer");
+        });
+      return;
+    }
+    void host
+      .run(async (session) => {
+        await session.prompt(text, { source: "rpc", ...attached });
+      })
+      .catch((err: unknown) => {
+        failed(err, "turn");
+      });
+  }
+}