Let an agent see the file.

// app/api/attachments/upload/route.ts — YOUR bucket, YOUR auth. The framework never sees the bytes.
import type { AttachmentRef } from "@nightowlsdev/core";
import { authenticate } from "@/lib/auth";
import { bucket, recordAttachment } from "@/lib/bucket";

export async function POST(req: Request): Promise<Response> {
  const authCtx = await authenticate(req);
  if (!authCtx) return Response.json({ error: "unauthorized" }, { status: 401 });

  const form = await req.formData();
  const file = form.get("file");
  const container = form.get("container");
  if (!(file instanceof File) || typeof container !== "string") {
    return Response.json({ error: "file and container required" }, { status: 400 });
  }

  // ⚠ KEEP THE REAL EXTENSION IN THE KEY. OpenRouter gates image URLs on a file-extension regex
  // (/^https?:\/\/.+\.(jpg|jpeg|png|gif|webp)(?:[?#].*)?$/i), so a signed URL over a bare UUID key
  // does not match — admission then refuses the URL and falls back to bytes, or drops the
  // attachment with `url-refused`. OpenRouter's PDF parsing keys on the filename too.
  const id = crypto.randomUUID();
  const dot = file.name.lastIndexOf(".");
  const key = `${authCtx.tenantId}/${container}/${id}${dot > 0 ? file.name.slice(dot) : ""}`;

  await bucket.put(key, file);
  await recordAttachment({
    id, key, container, tenantId: authCtx.tenantId,
    mediaType: file.type, filename: file.name, byteLength: file.size,
  });

  // The ref is the WHOLE wire payload — there is no url/path/key/bucket field to leak. A ref
  // carrying one is rejected at every entry, so this shape is the only thing that reaches a run.
  const ref: AttachmentRef = { id, mediaType: file.type, filename: file.name, bytes: file.size };
  return Response.json(ref);
}

// lib/attachments.ts — the ONLY code that turns a ref into something a model can read.
import type { AttachmentCanonical, ResolveAttachmentFn } from "@nightowlsdev/core";
import { attachmentRow, bucket } from "@/lib/bucket";

export const resolveAttachment: ResolveAttachmentFn = async (ref, scope, want) => {
  // YOUR OBLIGATION. `scope` is trusted and framework-built (never read off the request body);
  // `ref` is untrusted hints. A ref belonging to another container must resolve exactly like an
  // absent one — "not-found", never "forbidden" — or the reason string becomes an existence oracle
  // for ids in someone else's thread.
  const row = await attachmentRow(ref.id);
  if (!row || row.container !== scope.container || row.tenantId !== scope.tenantId) {
    return { kind: "unsupported", reason: "not-found" };
  }

  // `canonical` is the TRUSTED record. Admission and part construction read it exclusively, and the
  // per-file budget is enforced against canonical.byteLength — never against the ref's `bytes` hint.
  const canonical: AttachmentCanonical = {
    mediaType: row.mediaType,
    filename: row.filename,
    byteLength: row.byteLength,
  };
  const text = async () => new TextDecoder().decode(await bucket.bytes(row.key));

  // purpose "ingest" — a TOOL asked, through ctx.resolveAttachment. Bytes or text only: this arm
  // has no URL variant, by type.
  if (want.purpose === "ingest") {
    return row.mediaType.startsWith("text/")
      ? { kind: "text", canonical, text: await text() }
      : { kind: "bytes", canonical, data: await bucket.bytes(row.key) };
  }

  // purpose "model". `want.transportHint` is CONSERVATIVE and computed before anything is resolved:
  // "url-ok" only means the profile COULD accept a URL for this media class. Admission still tests
  // the final URL and canonical mediaType against the LIVE model's supportedUrls, and asks you once
  // more with "bytes-only" if it refuses. Answering with bytes is always legal.
  if (row.mediaType.startsWith("image/")) {
    return want.transportHint === "url-ok"
      ? { kind: "image", data: await bucket.signedUrl(row.key, 900), canonical }
      : { kind: "image", data: await bucket.bytes(row.key), canonical };
  }
  if (row.mediaType === "application/pdf") {
    return { kind: "pdf", data: await bucket.bytes(row.key), canonical };
  }
  if (row.mediaType.startsWith("text/")) {
    return { kind: "text", canonical, text: await text() };
  }

  // Anything no provider reads (docx, xlsx, video) is YOUR extraction problem. Saying so puts a
  // `resolution-failed` notice on the operator's screen instead of a silently missing document.
  return { kind: "unsupported", reason: `no transport for ${row.mediaType} — extract it host-side first` };
};

// lib/swarm.ts — the two fields FR-048 adds to the config you already have.
import { defineSwarm } from "@nightowlsdev/core";
import { resolveAttachment } from "@/lib/attachments";
import { agents, cost, modelFactory, models, storage } from "@/lib/swarm-config";

export const { engine } = defineSwarm({
  storage, agents, models, modelFactory, cost,

  resolveAttachment,
  // Post-resolution ceiling, checked against canonical.byteLength. Default 20 MiB.
  // `allowInsecureUrls` (default false) is the only way an http: URL is ever admitted: https plus a
  // private-address guard is the standing policy, and a data: URL is refused outright.
  attachments: { maxBytesPerFile: 10 * 1024 * 1024 },
});

"use client";
import { SwarmChat, SwarmProvider, previewContainerOf, type AttachmentRef } from "@nightowlsdev/react";

async function uploadToHost(file: File, container: string): Promise<AttachmentRef> {
  const form = new FormData();
  form.set("file", file);
  form.set("container", container);
  const res = await fetch("/api/attachments/upload", { method: "POST", body: form });
  if (!res.ok) throw new Error(`upload failed (${res.status})`);
  // Throwing marks THAT chip as failed. It never blocks the send: the text still goes.
  return (await res.json()) as AttachmentRef;
}

export function Chat({ threadId }: { threadId: string }) {
  return (
    <SwarmProvider
      theme="ink"
      // Both or neither: either endpoint alone is inert and chips render as plain labels.
      endpoints={{
        attachmentToken: "/api/swarm/attachments/token",
        attachmentPreview: "/api/swarm/attachments",
      }}
    >
      <SwarmChat
        agentSlug="coordinator"
        threadId={threadId}
        // The paperclip appears only when onUpload is wired AND the engine declares a class.
        onUpload={(file) => uploadToHost(file, previewContainerOf(threadId))}
      />
    </SwarmProvider>
  );
}

"use client";
import { useState } from "react";
import { AttachmentChip, useSwarmChat, type AttachmentRef } from "@nightowlsdev/react";

export function OwnComposer({ agentSlug, threadId }: { agentSlug: string; threadId: string }) {
  const chat = useSwarmChat({ agentSlug, threadId });
  const [text, setText] = useState("");
  const [refs, setRefs] = useState<AttachmentRef[]>([]);

  return (
    <form
      onSubmit={(e) => {
        e.preventDefault();
        // An ATTACHMENT-ONLY send is legal — "" plus one ref is a valid turn, as long as the engine
        // declares a class it can carry. `send(text, "slug")` still works; only the options object
        // can carry attachments.
        if (!text && refs.length === 0) return;
        void chat.send(text, { attachments: refs });
        setText("");
        setRefs([]);
      }}
    >
      {refs.map((ref) => (
        <AttachmentChip
          key={ref.id}
          attachment={ref}
          threadId={threadId}
          state="done"
          onRemove={() => setRefs((prev) => prev.filter((r) => r.id !== ref.id))}
        />
      ))}
      <input value={text} onChange={(e) => setText(e.target.value)} />

      {/* Per-ref outcomes of the LAST request: refs the server rejected or dropped over the cap.
          Nothing is silently discarded — surface these or the operator sends into a void. */}
      {chat.attachmentDispositions
        ?.filter((d) => d.disposition !== "accepted")
        .map((d) => <p key={d.id ?? d.reason}>{d.id ?? "attachment"}: {d.disposition} — {d.reason}</p>)}
    </form>
  );
}

// lib/attachment-preview.ts
import type { AttachmentPreviewResult, AttachmentPreviewScope } from "@nightowlsdev/runner-nextjs";
import { attachmentRow, bucket } from "@/lib/bucket";
import { attachmentPreviewSecret } from "@/lib/env";
import { runner } from "@/lib/runner";

// The route has already authenticated the caller, re-run the participation gate, and compared the
// caller's identity to the token's claims. What it CANNOT know is your bucket layout, so ownership
// is still yours to check: a foreign ref returns null and the route answers 404 — the same answer
// an unknown id gets, so nothing is confirmed to a prober.
async function resolvePreview(
  ref: { id: string },
  scope: AttachmentPreviewScope,
): Promise<AttachmentPreviewResult> {
  const row = await attachmentRow(ref.id);
  if (!row || row.container !== scope.container || row.tenantId !== scope.tenantId) return null;

  // { stream } proxies the bytes through your own origin — always safe to read.
  return { stream: await bucket.stream(row.key), mediaType: row.mediaType };

  // { redirect: await bucket.signedUrl(row.key, 900) } is also legal and answers 302 — but the
  // browser READS the redeem response to build a blob: URL, so the target must be CORS-readable.
  // If your CDN is not, return { stream }.
}

// Built ONCE and re-exported by the two route files below, so both handlers share one secret, one
// TTL and one resolver. Constructing it per route file also works, but then two files own two
// copies of that configuration.
export const preview = runner.attachmentPreviewRoutes({
  resolvePreview,
  secret: attachmentPreviewSecret,
  ttlMs: 15 * 60_000, // default; a 410 triggers exactly one transparent re-mint client-side
});

// A tool that reads an attachment. FR-054's ingestion pipeline uses this same handle.
import { defineTool } from "@nightowlsdev/core";
import { z } from "zod";

export const readAttachment = defineTool({
  name: "read_attachment",
  description: "Read the text of a document the user attached to this conversation.",
  inputSchema: z.object({ attachmentId: z.string() }),
  outputSchema: z.object({ text: z.string() }),
  execute: async ({ attachmentId }, ctx) => {
    // The fourth engine-populated handle. It is ingest-shaped BY TYPE — no URL arm exists to hand a
    // model — it closes over THIS run's trusted scope, and it is `undefined` (never a no-op faking
    // an `unsupported` result) when the host wired no resolver.
    if (!ctx.resolveAttachment) return { text: "no attachment resolver is configured" };

    const resolved = await ctx.resolveAttachment({ id: attachmentId });
    if (resolved.kind === "text") return { text: resolved.text };
    if (resolved.kind === "bytes") return { text: new TextDecoder().decode(resolved.data) };
    return { text: `unavailable: ${resolved.reason}` };
  },
});