Attach files to a message

.gitignore

@@ -13,7 +13,10 @@ docs/plans/
 !.env.example
 # Per-Bot egress proxies. Carries credentials in the URL, like .env does.
 egress.env
-node_modules/
+# No trailing slash, deliberately. With one, this pattern matches a DIRECTORY only, and a symlink
+# named node_modules is not a directory — so a sandbox that links its dependencies at the repo root
+# leaves three links git will happily commit. That happened.
+node_modules
 **/dist/
 app/src/lib/generated/application-config.ts
 .logs/

app/serve.ts

@@ -74,14 +74,33 @@ export function upstreamWebSocketHeaders(requestHeaders: Headers): Headers {
   return headers;
 }
 
+/**
+ * Bun's WebSocket client: the DOM one, plus the two things Bun adds and the browser does not.
+ *
+ * `bun-types` hands the global `WebSocket` over to `lib.dom` whenever DOM is in `lib`, and this
+ * project has DOM in `lib` for the browser code that is the rest of `app/`. What is left describes
+ * the BROWSER's client, which has no `terminate()` and takes subprotocols where Bun takes options.
+ * This file only ever runs under Bun and uses both.
+ *
+ * Stated as an extension of the DOM type rather than by reaching for `Bun.WebSocket`, because that
+ * interface is written for projects WITHOUT DOM in `lib` and degrades to `{}` here — its events
+ * come back untyped, which costs more than the two members it would buy. Same socket either way;
+ * this is a type-level correction, not a different client.
+ */
+export type BunWebSocket = WebSocket & { terminate(): void };
+export const BunWebSocket = globalThis.WebSocket as unknown as {
+  new (url: string | URL, options?: { headers?: HeadersInit }): BunWebSocket;
+  readonly OPEN: number;
+};
+
 type WebSocketBridge = {
-  upstream: WebSocket;
+  upstream: BunWebSocket;
   attach: (downstream: ServerWebSocket<WebSocketBridge>) => void;
   dispose: () => void;
 };
 
 /** Own the upstream before awaiting its handshake, including any immediate welcome frames. */
-function prepareWebSocketBridge(upstream: WebSocket, signal: AbortSignal) {
+function prepareWebSocketBridge(upstream: BunWebSocket, signal: AbortSignal) {
   upstream.binaryType = "arraybuffer";
   let downstream: ServerWebSocket<WebSocketBridge> | undefined;
   const pending: (string | ArrayBuffer)[] = [];
@@ -185,7 +204,7 @@ if (import.meta.main) {
       },
       message(ws, message) {
         const { upstream } = ws.data;
-        if (upstream.readyState === WebSocket.OPEN) {
+        if (upstream.readyState === BunWebSocket.OPEN) {
           upstream.send(message);
         } else {
           ws.close(1011, "Upstream connection closed");
@@ -202,13 +221,13 @@ if (import.meta.main) {
       if (isApiCall(url.pathname)) {
         const target = SERVER + url.pathname + url.search;
         if (request.headers.get("upgrade")?.toLowerCase() === "websocket") {
-          const upstream = new WebSocket(target.replace(/^http/, "ws"), {
+          const upstream = new BunWebSocket(target.replace(/^http/, "ws"), {
             headers: upstreamWebSocketHeaders(request.headers),
           });
           const bridge = prepareWebSocketBridge(upstream, request.signal);
           if (
             !(await bridge.opened) ||
-            upstream.readyState !== WebSocket.OPEN
+            upstream.readyState !== BunWebSocket.OPEN
           ) {
             bridge.data.dispose();
             return new Response("Could not connect to the upstream WebSocket", {

app/src/components/channels/channel-chat.tsx

@@ -1,11 +1,13 @@
 import type { Message } from "@ag-ui/core";
 import {
+  type Attachment,
   UseAgentUpdate,
   useAgent,
   useCopilotKit,
 } from "@copilotkit/react-core/v2";
 import { useMutation, useQuery } from "@tanstack/react-query";
 import { useCallback, useEffect, useRef, useState } from "react";
+import { attachmentModality } from "@/components/channels/chat-messages";
 import { toAgentOptions } from "@/components/channels/composer";
 import { ConversationView } from "@/components/channels/conversation-view";
 import {
@@ -14,6 +16,7 @@ import {
   transcriptMessages,
 } from "@/components/channels/transcript-messages";
 import { agentListQueryOptions } from "@/lib/agents/queries";
+import { attachmentUrl } from "@/lib/channels/attachments";
 import {
   recordChannelActivityMutationOptions,
   setChannelBusy,
@@ -126,6 +129,95 @@ function mergeStoredMessages(local: Message[], stored: Message[]): Message[] {
   ];
 }
 
+/**
+ * The uploaded id and filename an `Attachment` carries once it is `ready`, read from the
+ * `metadata` the composer's `onUpload` stamped on it — see `composer/attachments.ts`. Not the
+ * SDK's own `attachment.id`, which is a client-side handle for the upload placeholder rather than
+ * the id this deployment stored the file under.
+ */
+function uploadedAttachment(attachment: Attachment): {
+  attachmentId: string;
+  filename?: string;
+} {
+  const metadata = attachment.metadata as
+    | { attachmentId?: unknown; filename?: unknown }
+    | undefined;
+  const attachmentId = metadata?.attachmentId;
+  if (typeof attachmentId !== "string") {
+    throw new Error("Attachment is missing its uploaded id.");
+  }
+  const filename =
+    typeof metadata?.filename === "string" ? metadata.filename : undefined;
+  return filename ? { attachmentId, filename } : { attachmentId };
+}
+
+/**
+ * One attachment, turned into the part shape a stored message carries.
+ *
+ * THE MODALITY COMES FROM THE BYTES, NOT FROM `attachment.type`, AND THIS IS THE ONLY PLACE IT CAN.
+ *
+ * `attachment.type` is the browser's claim, fixed before the upload and never reconciled with what
+ * the file turned out to be. The server stopped trusting it — `resolvePart` decides an attachment's
+ * modality with `classifyAttachment` on its own sniffed `mimeType` — but that correction lives on
+ * the server and never comes back here. What this function writes IS the stored message, so a
+ * `document` written here is what every later render of that message reads, for ever: a screenshot
+ * whose part the browser mislabelled drew a grey file card over the picture, and the transcript's
+ * document probe then paid a whole-file read per render for the privilege.
+ *
+ * Narrowed through the source union rather than read straight off, for the reason `parkedTiles` in
+ * `chat-transcript.tsx` narrows the same field: a `data` source's `mimeType` is `file.type`, the
+ * very claim being refused, and only a `url` source has been past the server. `attachmentModality`
+ * falls back to the declared type when there is no corroborated one, so an attachment that somehow
+ * arrives unuploaded is written exactly as it used to be.
+ *
+ * The comment this replaces said only "image" and "document" reach here because the composer's
+ * upload config accepts no other kind of file. That reason is no longer true — the config's
+ * `accept` is now the wildcard, and it is `screenPickedFiles` that holds the line. The conclusion still
+ * holds; the justification had rotted, which is why the modality is now derived rather than cast.
+ */
+function toAttachmentPart(attachment: Attachment) {
+  const { attachmentId, filename } = uploadedAttachment(attachment);
+  const { source } = attachment;
+  const mimeType =
+    source.type === "url" && source.mimeType ? source.mimeType : undefined;
+  return {
+    type: attachmentModality(attachment.type, mimeType),
+    source: { type: "url" as const, value: attachmentUrl(attachmentId) },
+    metadata: filename ? { attachmentId, filename } : { attachmentId },
+  };
+}
+
+/**
+ * A plain string when there is nothing attached, exactly as every message in every channel has
+ * always been sent — never a single-element array wrapping the same text, which every existing
+ * reader would take a different path for no gain. With attachments, the text goes first as its
+ * own part and is left out entirely when empty, since an empty text part is noise the model has
+ * to read past.
+ *
+ * Exported for the test that pins this wire format. Reaching it through `deliver`/`say` would mean
+ * standing up `useAgent`'s runtime, the thread join and the ready/join gates around it just to
+ * observe a pure string-in-object-out mapping — none of that machinery bears on what this function
+ * decides, so a narrow export is the honest way to test the contract without restructuring the
+ * module around a test.
+ */
+export function toMessageContent(
+  trimmed: string,
+  attachments: readonly Attachment[],
+) {
+  if (attachments.length === 0) return trimmed;
+  const refs = attachments.map(toAttachmentPart);
+  return trimmed ? [{ type: "text" as const, text: trimmed }, ...refs] : refs;
+}
+
+/** What the roster's "last thing said" reads when a message carried no caption. */
+function describeAttachments(attachments: readonly Attachment[]): string {
+  if (attachments.length === 1) {
+    const { filename } = uploadedAttachment(attachments[0]);
+    return filename ? `Sent ${filename}` : "Sent an attachment";
+  }
+  return `Sent ${attachments.length} attachments`;
+}
+
 /**
  * One channel's conversation with one coworker.
  *
@@ -408,6 +500,36 @@ export function ChannelChat({
   // Run failures arrive as events and are reported only for turns started in this mount.
   const [runError, setRunError] = useState<string | null>(null);
   const awaitingReply = useRef(false);
+  /**
+   * WHY THIS TURN ENDED WITHOUT AN ANSWER, KEPT WHERE `deliver` CAN STILL SEE IT — because the one
+   * thing that knows is a subscriber, and the one thing that has to act on it is an `await`.
+   *
+   * `copilotkit.runAgent` DOES NOT REJECT ON A FAILED RUN. `CopilotKitCore.runAgent` catches
+   * everything the agent throws, reports it through `emitError` as `AGENT_RUN_FAILED`, and returns
+   * `{ result: undefined, newMessages: [] }` — a value indistinguishable from a run that finished
+   * with nothing to say. So a gateway 503, a stream that dies, a model that refuses the request:
+   * every one of them arrived here as a resolved promise, and `say` reported success for a turn
+   * that never reached the server.
+   *
+   * WHAT THAT COST, WHICH IS THE REASON THIS EXISTS. `say` resolving is what every caller reads as
+   * "it went". The composer clears the box and gives up the chips it was riding; the queue empties
+   * into a draft nothing retries; `conversation-view.tsx` never runs either of the failure paths it
+   * has written for exactly this. The person is left with the failed turn in the transcript and a
+   * notice under it, the words unretryable, and the files behind them staged rows that nothing on
+   * any screen points at any more. The notice is honest and everything under it was not.
+   *
+   * READ OFF THE SAME `fail` THE NOTICE IS, and deliberately not from a second subscription of its
+   * own. `fail` already answers the one question a separate subscriber would get wrong: a turn the
+   * PERSON stopped also reaches `onRunFailed`, with an abort, and `onStop` clears `awaitingReply`
+   * before it — so Stop is not a failure here and nothing restores a draft somebody chose to end.
+   *
+   * ONE SLOT FOR ONE TURN AT A TIME, the same assumption `awaitingReply` beside it already makes.
+   * Two overlapping turns — a component button pressed during a composer send — would have the
+   * second clear the first's reason, which reports the earlier turn as successful. That is the
+   * pre-existing shape of `awaitingReply`, not a new one, and narrowing it means giving a run a
+   * handle that `copilotkit.runAgent` does not hand back.
+   */
+  const turnFailure = useRef<string | null>(null);
   const assistantMessagesBeforeRun = useRef<Set<string>>(new Set());
 
   /*
@@ -466,7 +588,11 @@ export function ChannelChat({
    * Everything `say` does once it has something worth sending, split out so the counter it is
    * wrapped in covers every way out of here, a throw included.
    */
-  const deliver = async (trimmed: string, skillInstructions: string[]) => {
+  const deliver = async (
+    trimmed: string,
+    skillInstructions: string[],
+    attachments: Attachment[],
+  ) => {
     // Wait briefly for the runtime agent instance before adding the message.
     if (!isReadyRef.current) {
       await Promise.race([
@@ -490,6 +616,7 @@ export function ChannelChat({
     const target = agentRef.current;
 
     setRunError(null);
+    turnFailure.current = null;
     assistantMessagesBeforeRun.current = new Set(
       target.messages
         .filter((message) => message.role === "assistant")
@@ -518,11 +645,11 @@ export function ChannelChat({
     }
 
     target.addMessage({
-      content: trimmed,
+      content: toMessageContent(trimmed, attachments),
       id: newId(),
       role: "user",
     });
-    report(trimmed, null);
+    report(trimmed || describeAttachments(attachments), null);
 
     // Providers reject later turns if prior tool calls have no result; repair before sending.
     const repaired = repairUnansweredToolCalls(target.messages);
@@ -536,6 +663,30 @@ export function ChannelChat({
     } finally {
       setRunsInFlight((count) => count - 1);
     }
+
+    /*
+     * A TURN THAT DID NOT HAPPEN FAILS THE SEND, which is the only way anything upstream can tell.
+     * See `turnFailure` for why the resolved promise above says nothing about that.
+     *
+     * AFTER the `finally`, not inside the `try`: the run is over either way, so the counter that
+     * draws the Stop button must come down before this throws. Throwing from inside would leave
+     * `runsInFlight` high for a run that has already ended.
+     *
+     * WHAT THE THROW REACHES, so it is clear this is a message and not a crash. The composer's
+     * `catch` puts the words and the chips back; `conversation-view.tsx` puts a drained queue back
+     * as retryable entries carrying their files. Nothing here reports the failure — `runError` was
+     * already set from the same `fail` that set this, and the transcript already draws it — so this
+     * adds a retry, not a second sentence.
+     *
+     * THE MESSAGE STAYS ON SCREEN. `deliver` added it above and nothing takes it away: it is what
+     * the failed turn WAS, it is what the notice under it is about, and removing it would delete a
+     * partial answer that a mid-stream failure had already produced. The restored draft beside it
+     * is the retry, the same way a failed composer send has always put its words back while the
+     * transcript kept the turn.
+     */
+    if (turnFailure.current !== null) {
+      throw new Error(turnFailure.current);
+    }
   };
 
   /**
@@ -546,17 +697,24 @@ export function ChannelChat({
    * keeping here rather than in the view: the view sees only the turns it started itself, and a
    * queue that drains on the wrong one of those posts a correction into the middle of an answer.
    */
-  const say = async (text: string, skillInstructions: string[] = []) => {
+  const say = async (
+    text: string,
+    skillInstructions: string[] = [],
+    attachments: Attachment[] = [],
+  ) => {
     const trimmed = text.trim();
-    if (!trimmed) return;
+    // A pasted screenshot with no caption is still a message to send: `canSendDraft` already
+    // unlocks the button for exactly this case, so refusing it here would leave the button
+    // enabled and inert.
+    if (!trimmed && attachments.length === 0) return;
 
     turnsRef.current += 1;
     setTurnsInFlight(turnsRef.current);
     if (turnsRef.current === 1) {
       void setChannelBusy({ channelId: channel.id, busy: true });
     }
     try {
-      await deliver(trimmed, skillInstructions);
+      await deliver(trimmed, skillInstructions, attachments);
     } finally {
       turnsRef.current -= 1;
       setTurnsInFlight(turnsRef.current);
@@ -572,6 +730,9 @@ export function ChannelChat({
     const fail = (message: string) => {
       if (!awaitingReply.current) return;
       awaitingReply.current = false;
+      // Both halves of one fact: the sentence the transcript shows, and the reason `deliver` throws
+      // so the draft behind the turn is restored rather than counted as sent. See `turnFailure`.
+      turnFailure.current = message;
       setRunError(message);
     };
     const subscription = agent.subscribe?.({
@@ -604,9 +765,16 @@ export function ChannelChat({
 
   /**
    * Component buttons speak as user turns without forcing every transcript card to re-render.
+   *
+   * The rejection is swallowed HERE rather than left to the void, and that is not a style choice:
+   * `say` throws on a failed turn now (see `turnFailure`), and a voided promise with nothing on the
+   * end of it is an unhandled rejection — in this repository's test runner, a failure attributed to
+   * whichever test happened to be running when it surfaced. There is nothing to restore for this
+   * caller either way: the words came from a button inside a rendered card, not from a box somebody
+   * is still holding, and the failed turn is already reported by `runError` under the transcript.
    */
   const askFromComponent = useCallback((text: string) => {
-    void sayRef.current(text);
+    void sayRef.current(text).catch(() => undefined);
   }, []);
 
   /**
@@ -618,9 +786,12 @@ export function ChannelChat({
     if (!pending) return;
     seedRef.current = null;
 
-    void sayRef.current(
-      typeof pending.content === "string" ? pending.content : "",
-    );
+    // Swallowed for the reason `askFromComponent` above records: `say` throws on a failed turn, and
+    // the seed has no box to go back into — it was typed on a screen that has already navigated
+    // away. The transcript keeps the seeded message and the notice under it says what happened.
+    void sayRef
+      .current(typeof pending.content === "string" ? pending.content : "")
+      .catch(() => undefined);
 
     // Keep `seed` in state; transcriptMessages gives it up once the agent holds a user turn.
   }, []);
@@ -629,6 +800,7 @@ export function ChannelChat({
     <ConversationProvider ask={askFromComponent}>
       <ConversationView
         agents={toAgentOptions(agentProfiles, channel.agentIds)}
+        channelId={channel.id}
         /*
          * THE TURN, not the run. `say` waits for the runtime agent and the join before a run starts,
          * and `agent.isRunning` alone leaves that gap unmarked — which is the one moment the
@@ -677,7 +849,7 @@ export function ChannelChat({
               Boolean(instruction),
             );
 
-          await say(draft.text, skillInstructions);
+          await say(draft.text, skillInstructions, draft.attachments);
         }}
         /**
          * Stop through the core so the abort signal reaches frontend tools; `say` repairs any