Skip to content

Open-source AI coworkers that each get a computer of their own: a browser, files and tools, with every action decided before it happens and recorded after. Bring any AG-UI agent.

13.3 KB
Raw Blame
import type { AttachmentsConfig } from "@copilotkit/react-core/v2";
import {
  ACCEPTED_IMAGE_MIME,
  ACCEPTED_TEXT_MIME,
  attachmentUrl,
  MAX_IMAGE_BYTES,
} from "@/lib/channels/attachments";

/**
 * Uploads a picked file to this deployment and hands the composer a link to it, never the bytes.
 *
 * Neither `AttachmentUploadResult` nor `AttachmentUploadError` is exported by anything installed
 * here: `@copilotkit/shared` declares both, but it is not a dependency of `app/` — the only
 * installed CopilotKit package in this workspace is `react-core`, and its `v2` entry point does
 * not re-export these two. They are derived instead from `AttachmentsConfig["onUpload"]` /
 * `["onUploadFailed"]`, the one signature that IS public, so they can never drift from what the
 * SDK actually calls.
 */
type AttachmentUploadResult = Awaited<
  ReturnType<NonNullable<AttachmentsConfig["onUpload"]>>
>;
type AttachmentUploadError = Parameters<
  NonNullable<AttachmentsConfig["onUploadFailed"]>
>[0];

/** The shape `POST /api/channels/:channelId/attachments` sends back on success. */
type UploadedAttachment = {
  id: string;
  name: string;
  mimeType: string;
};

/**
 * The SDK's `onUpload`, scoped to one channel.
 *
 * `fetch` directly rather than `client()` from `@/lib/client`: `client()` JSON-stringifies its
 * body and sets a JSON content type, neither of which can carry a multipart upload.
 *
 * Supplying this is what keeps the bytes out of browser state: with `onUpload` set, the SDK never
 * calls its own `readFileAsBase64` and never retains the `File` it was handed, so no copy of the
 * bytes lives on past this call. Returning a `url` source rather than a `data` one is the other
 * half of that: it is what puts a small reference in the sent message instead of megabytes of
 * base64 riding along in it.
 */
export function uploadToChannel(
  channelId: string,
  uploadGroup: string,
): (file: File) => Promise<AttachmentUploadResult> {
  return async (file: File): Promise<AttachmentUploadResult> => {
    const formData = new FormData();
    formData.append("file", file);
    /*
     * WHICH COMPOSER STAGED IT, so the server's cap counts the set this composer can see.
     *
     * The cap is per message. The composer counts what is on its own screen; without this field the
     * server counted every unsent row this person had in this channel, which is not the same set
     * the moment anything leaves a row behind — a closed tab, a stopped run, a removed queued
     * message. The client would then accept a pick the server refused with a 409 naming files that
     * were on nobody's screen, and eight such orphans locked uploads in that channel until the
     * sweeper's window expired. Sending the group is what makes the two sides count the same rows.
     */
    formData.append("uploadGroup", uploadGroup);

    const response = await fetch(`/api/channels/${channelId}/attachments`, {
      method: "POST",
      credentials: "include",
      body: formData,
    });

    /*
     * READ ONCE, FOR EITHER OUTCOME, AND NEVER TRUSTED.
     *
     * The refusal path has been careful since a body that was not JSON put "Failed to parse JSON"
     * on screen as the reason a file was rejected. The success path was not: it went straight to
     * `as UploadedAttachment`, which is a cast and not a check, so the same malformed body threw a
     * raw `SyntaxError` that the SDK reported as the refusal — and a body that parsed but carried
     * no `id` was worse, because it succeeded: `attachmentUrl(undefined)` became a chip pointing at
     * `/api/attachments/undefined`, Send unlocked, and the message went out carrying a link to no
     * attachment. Both halves of one response are held to the same standard here.
     */
    const body: unknown = await response.json().catch(() => undefined);
    // Named after the file rather than left empty, for every way this can go wrong. It is the only
    // sentence anybody gets: the composer keeps the string verbatim and shows it as the reason.
    const couldNotUpload = new Error(
      `Couldn't upload "${file.name}". Try again.`,
    );

    if (!response.ok) {
      // The server phrases refusals in the product's voice — naming the mime type or the limit
      // that was actually hit — so its sentence is preferred whenever it has really sent one.
      throw refusalIn(body) ?? couldNotUpload;
    }

    if (!isUploadedAttachment(body)) {
      throw couldNotUpload;
    }

    return {
      type: "url",
      value: attachmentUrl(body.id),
      mimeType: body.mimeType,
      metadata: { attachmentId: body.id, filename: body.name },
    };
  };
}

/**
 * The server's own sentence, when it has actually sent one.
 *
 * `??` was doing this job and could not: it steps in only for `null` and `undefined`, so
 * `{"error":""}` — or a whitespace-only one, or a number — was preferred over the fallback and
 * reached the strip as a file refused with NO REASON BESIDE IT. A refusal with nothing to read is
 * indistinguishable from a bug, which is the one thing this whole path exists to avoid.
 */
function refusalIn(body: unknown): Error | undefined {
  if (typeof body !== "object" || body === null) {
    return undefined;
  }
  const { error } = body as { error?: unknown };
  if (typeof error !== "string" || error.trim().length === 0) {
    return undefined;
  }
  return new Error(error);
}

/**
 * Every field this function is about to hand the SDK, present and a string.
 *
 * `id` is checked for content and not merely for type, because it is the one that becomes a URL:
 * an empty id makes `/api/attachments/`, which is a different endpoint entirely rather than a
 * broken one.
 */
function isUploadedAttachment(body: unknown): body is UploadedAttachment {
  if (typeof body !== "object" || body === null) {
    return false;
  }
  const { id, name, mimeType } = body as Record<string, unknown>;
  return (
    typeof id === "string" &&
    id.length > 0 &&
    typeof name === "string" &&
    typeof mimeType === "string"
  );
}

/**
 * WHAT THE `+` BUTTON'S FILE DIALOG OFFERS — A HINT, AND THE ONLY PLACE `accept` IS STILL SPENT.
 *
 * This is NOT a gate. A file dialog's `accept` greys files out; it refuses nothing, every desktop
 * browser offers a way past it, and drag and paste never see it at all. So it may be as narrow as
 * is useful, where the SDK's `accept` (see `attachmentsConfigFor`) may not be narrow at all.
 *
 * THE EXTENSIONS ARE HERE FOR THE SAME REASON THE `unnamed` BRANCH EXISTS IN `picked-files.ts`. A
 * MIME-only list is matched against what the browser CLAIMS a file is, and the whole point of that
 * branch is that for a `.txt` dragged out of an editor — or anything with an extension the
 * platform has no mapping for — the browser claims `application/octet-stream` or nothing. Listing
 * the media types alone therefore greys out, in the dialog, exactly the files this composer went
 * to some trouble to accept everywhere else. `matchesAcceptFilter` and every browser's dialog both
 * read a leading-dot entry as a filename suffix, so the two doors now agree.
 */
export const FILE_PICKER_ACCEPT = [
  ...ACCEPTED_IMAGE_MIME,
  ...ACCEPTED_TEXT_MIME,
  ".png",
  ".jpg",
  ".jpeg",
  ".gif",
  ".webp",
  ".txt",
  ".md",
  ".csv",
  ".json",
].join(",");

/**
 * `AttachmentsConfig` for one channel's composer.
 *
 * `accept` IS THE WILDCARD, AND THAT IS THE WHOLE OF THE TYPE POLICY MOVING TO ONE PLACE RATHER
 * THAN BEING ABANDONED.
 *
 * It used to be `[...ACCEPTED_IMAGE_MIME, ...ACCEPTED_TEXT_MIME].join(",")`, and that was a second
 * gate standing behind `screenPickedFiles` — a stricter one, applying a different rule, phrased for
 * a machine. `useAttachments.processFiles` runs it with `matchesAcceptFilter`, whose non-wildcard,
 * non-extension branch is a bare `file.type === filter`. `screenPickedFiles` deliberately passes a
 * claim that names no format (`application/octet-stream`, `""` — see the long note at
 * `picked-files.ts`) so the server can sniff the bytes; none of those strings equals any of the
 * eight, so the SDK refused every one of them before a request was ever made, with
 * `File "notes.txt" is not accepted. Supported types: image/png,…`. That branch was dead in the
 * running app, the drift it exists to close was still open, and the sentence somebody read was the
 * one `stageFiles` promises a screened file can never produce.
 *
 * Widening the list instead was the other option and is not enough: `""` cannot be written as an
 * accept entry at all, and `namesNoFormat` also passes anything not shaped like a MIME type, which
 * is an open set. There is no string that means what the screen means.
 *
 * WHAT THIS COSTS, STATED PLAINLY: nothing, because the SDK's filter was never reachable except
 * through us. `stageFiles` is the only caller of `processFiles` — the composer supplies its own
 * drop handler and its own `onChange`, so the hook's `handleDrop` and `handleFileUpload` are never
 * used — and the hook's own `document` paste listener is inert here, because it is scoped by a
 * `containerRef` this composer deliberately never hands it (see `containerRef` in `composer.tsx`).
 * So every file that reaches `processFiles` has already been through `screenPickedFiles`, which
 * enforces kind, BOTH size ceilings and the per-message cap — all of which the SDK's filter does
 * not — and phrases its refusals for a person. The narrow list is kept where it is honest about
 * being a hint: `FILE_PICKER_ACCEPT`, above, on the file dialog.
 *
 * `maxSize` is `MAX_IMAGE_BYTES`, the larger of the two ceilings: the SDK config has only one
 * number for every kind of file. The tighter `MAX_FILE_BYTES` limit for text attachments is
 * enforced by our own pre-check ahead of upload, and again by the server on arrival — which is
 * the authority either way, so letting a text file past this one number costs nothing. It is left
 * in place, unlike `accept`, because it can only ever agree with the screen: the loosest thing
 * `screenPickedFiles` passes is a file of exactly `MAX_IMAGE_BYTES`, so this backstop cannot fire
 * on a file we accepted.
 */
export function attachmentsConfigFor(
  channelId: string,
  uploadGroup: string,
  onUploadFailed: (error: AttachmentUploadError) => void,
  /**
   * EVERY SERVER ROW THIS COMPOSER CREATES, REPORTED THE MOMENT IT EXISTS.
   *
   * `onUpload`'s answer normally reaches the composer the long way round, by the SDK writing it
   * onto the placeholder it minted — and that write is a no-op if the placeholder is gone, which is
   * what happens when somebody removes a chip whose upload is still in flight. The row is on the
   * server by then and the only handle to it was in that discarded answer, so the count the server
   * enforces and the count the screen shows drift apart by one, and the next pick is refused with a
   * 409 naming a file nobody can see. That is verbatim the failure `uploadGroup` was added to end.
   *
   * So the id is reported here as well, where it cannot be dropped, and `composer.tsx` reconciles
   * what it was told against what is actually on the strip. It is a separate channel rather than a
   * `wasCancelled(placeholderId)` predicate on the way in — the shape that suggests itself — for a
   * blunt reason: `onUpload` is handed a `File` and nothing else. The SDK mints the placeholder id
   * itself and never tells us which one this call belongs to, so there is no id here to be asked
   * about. Reporting the row and reconciling afterwards needs no such correlation.
   */
  onUploaded: (attachmentId: string) => void,
): AttachmentsConfig {
  const upload = uploadToChannel(channelId, uploadGroup);
  return {
    enabled: true,
    accept: "*/*",
    maxSize: MAX_IMAGE_BYTES,
    onUpload: async (file) => {
      const uploaded = await upload(file);
      const rowId = stagedRowId(uploaded);
      /*
       * `uploadToChannel` has already refused any answer without a non-empty `id`
       * (`isUploadedAttachment`), so this is narrowing rather than a real branch — `metadata` is
       * declared `unknown` by the SDK and has to be re-read as something. It is not silently
       * skipped if it ever does come back empty: the row would be one this composer never learned
       * about, which is the sweeper's to collect, and pretending otherwise by passing `undefined`
       * down would put `DELETE /api/attachments/undefined` on the wire.
       */
      if (rowId !== undefined) {
        onUploaded(rowId);
      }
      return uploaded;
    },
    onUploadFailed,
  };
}

/**
 * The server row an SDK attachment stands for, if it stands for one.
 *
 * `metadata` is `unknown` on the SDK's `Attachment` — it is whatever `onUpload` chose to return —
 * so every reader has to narrow it, and this is the one place that knows what we put there. Both
 * the composer's reconciler and this file's `onUpload` wrapper read it through here rather than
 * each spelling out the same cast, because the two must never disagree about what counts as a row.
 *
 * `undefined` for an attachment still uploading, which has no row yet, and for one the SDK built
 * itself without our `onUpload` — neither has anything on the server to give back.
 */
export function stagedRowId(
  carrier: { metadata?: unknown } | undefined,
): string | undefined {
  const metadata = carrier?.metadata as { attachmentId?: unknown } | undefined;
  return typeof metadata?.attachmentId === "string"
    ? metadata.attachmentId
    : undefined;
}