@openparachute/vault 0.7.3-rc.13 → 0.7.3-rc.3

package/core/src/mcp.ts

@@ -1,5 +1,5 @@
 import { Database } from "bun:sqlite";
-import type { Store, Note, QueryOpts, Attachment } from "./types.js";
+import type { Store, Note, QueryOpts } from "./types.js";
 import { transactionAsync } from "./txn.js";
 import * as noteOps from "./notes.js";
 import { filterMetadata, MAX_BATCH_SIZE, validateExtension, ExtensionValidationError, validatePath } from "./notes.js";
@@ -43,40 +43,8 @@ import {
   parseContentRange,
   applyContentRange,
   contentRangeRequiresContent,
-  parseAttachmentContentRange,
-  alignByteWindow,
   MIN_CONTENT_LENGTH,
 } from "./content-range.js";
-import {
-  BLOCKED_ATTACHMENT_EXTENSIONS,
-  ATTACHMENT_MIME_TYPES,
-  sanitizeAttachmentExtension,
-  mimeForAttachmentExtension,
-} from "./attachment/policy.js";
-import {
-  computeTicketTtlMs,
-  generateTicketId,
-  MAX_TICKET_UPLOAD_BYTES,
-  type AttachmentTicket,
-  type AttachmentTicketProvider,
-} from "./attachment/tickets.js";
-import {
-  MAX_ATTACHMENT_IMAGE_BYTES,
-  type AttachmentBytesProvider,
-} from "./attachment/bytes-provider.js";
-
-/**
- * A single MCP tool-result content block. Mirrors the subset of the MCP SDK's
- * `CallToolResult.content` shape this codebase actually emits — a plain text
- * block (the existing, universal shape) or a real image block (`read-attachment`'s
- * image branch, D3). Kept as a local, minimal type rather than importing the
- * SDK's own (broader — audio, resource links, ...) union, since core has no
- * dependency on `@modelcontextprotocol/sdk` today and this is the only shape
- * any tool here produces.
- */
-export type McpContentBlock =
-  | { type: "text"; text: string }
-  | { type: "image"; data: string; mimeType: string };
 
 export interface McpToolDef {
   name: string;
@@ -95,17 +63,6 @@ export interface McpToolDef {
    * future addition that forgets to stamp this gets the safer treatment.
    */
   requiredVerb: "read" | "write" | "admin";
-  /**
-   * OPTIONAL override for how `execute()`'s return value becomes MCP
-   * `content` blocks. Every tool WITHOUT this wraps its result as the single
-   * `JSON.stringify` text block the HTTP layer has always produced
-   * (`src/mcp-http.ts`) — unchanged default behavior. `read-attachment`'s
-   * image branch is the only current user: it needs a REAL `{type:"image"}`
-   * block alongside the row-JSON text block so the model actually SEES the
-   * picture, not just its metadata (D3, attachments-for-agents design "the
-   * one wrapper change").
-   */
-  resultContent?: (result: unknown) => McpContentBlock[];
 }
 
 // ---------------------------------------------------------------------------
@@ -123,7 +80,7 @@ export interface McpToolDef {
  */
 function structuredError(
   message: string,
-  fields: { error_type: string; field?: string; hint?: string } & Record<string, unknown>,
+  fields: { error_type: string; field?: string; hint?: string },
 ): Error {
   return Object.assign(new Error(message), fields);
 }
@@ -197,172 +154,6 @@ function removeWikilinkBrackets(content: string, targetPath: string): string {
   return content;
 }
 
-// ---------------------------------------------------------------------------
-// read-attachment helpers (Wave 2 model lane — D2-D5)
-// ---------------------------------------------------------------------------
-
-/** Non-`text/*` mime types `read-attachment` still treats as text (D2's "text/* + TEXT_MIMES allowlist"). `text/csv` and `text/markdown` already match `text/*` via ATTACHMENT_MIME_TYPES, so they need no entry here. */
-const TEXT_MIME_ALLOWLIST = new Set([
-  "application/json",
-  "application/ndjson",
-  "application/x-ndjson",
-  "application/yaml",
-  "application/x-yaml",
-]);
-
-function baseMime(mimeType: string): string {
-  return mimeType.split(";")[0]!.trim().toLowerCase();
-}
-
-function isTextMime(mimeType: string): boolean {
-  const base = baseMime(mimeType);
-  return base.startsWith("text/") || TEXT_MIME_ALLOWLIST.has(base);
-}
-
-function isImageMime(mimeType: string): boolean {
-  return baseMime(mimeType).startsWith("image/");
-}
-
-function isAudioOrVideoMime(mimeType: string): boolean {
-  const base = baseMime(mimeType);
-  return base.startsWith("audio/") || base.startsWith("video/");
-}
-
-/**
- * Effective mime for `read-attachment` — same discipline the REST byte-serve
- * route uses (`src/routes.ts`'s `GET /storage/<path>`): the stored file's
- * EXTENSION wins over the row's `mime_type` column, since the row's mime is
- * caller-asserted at upload time and never verified against the bytes. Falls
- * back to the row's mime_type, then `application/octet-stream`.
- */
-function effectiveAttachmentMime(attachment: Attachment): string {
-  const ext = sanitizeAttachmentExtension(attachment.path);
-  return ATTACHMENT_MIME_TYPES[ext] ?? attachment.mimeType ?? "application/octet-stream";
-}
-
-/** Stat the attachment's bytes, or throw the `attachment_binary_missing` refusal (D5's "row outlived bytes" case — e.g. an audio-retention eviction). */
-async function statAttachmentOrMissing(
-  attachment: Attachment,
-  provider: AttachmentBytesProvider,
-): Promise<{ size: number }> {
-  const stat = await provider.stat(attachment);
-  if (!stat) {
-    throw structuredError(`Attachment binary missing: "${attachment.id}"`, {
-      error_type: "attachment_binary_missing",
-      how_to:
-        "the attachment row exists but its bytes are gone (e.g. an audio-retention eviction after transcription) — this content can't be read",
-    });
-  }
-  return stat;
-}
-
-/**
- * Text branch: byte-windowed read using the exact query-notes pagination
- * contract (`content`/`content_offset`/`content_total_length`/
- * `content_next_offset`). Does a BOUNDED positional read — never the whole
- * file — via `alignByteWindow` (see its doc comment for the exact window
- * the provider is asked to fetch).
- */
-async function readTextAttachment(
-  attachment: Attachment,
-  mimeType: string,
-  params: Record<string, unknown>,
-  provider: AttachmentBytesProvider,
-): Promise<Record<string, unknown>> {
-  const range = parseAttachmentContentRange(params.content_offset, params.content_length);
-  const stat = await statAttachmentOrMissing(attachment, provider);
-  const total = stat.size;
-
-  if (range.offset >= total) {
-    return {
-      attachment_id: attachment.id,
-      mime_type: mimeType,
-      content: "",
-      content_offset: total,
-      content_total_length: total,
-      content_next_offset: null,
-    };
-  }
-
-  const rawStart = Math.max(0, range.offset - 3);
-  // +1: alignByteWindow's end-boundary check reads the byte AT the window's
-  // exclusive end — see its doc comment precondition.
-  const rawEnd = Math.min(total, range.offset + range.length + 1);
-  const raw = await provider.readRange(attachment, rawStart, rawEnd);
-  const fields = alignByteWindow(raw, rawStart, range, total);
-
-  return {
-    attachment_id: attachment.id,
-    mime_type: mimeType,
-    ...fields,
-  };
-}
-
-/**
- * Image branch: whole-file read, gated by {@link MAX_ATTACHMENT_IMAGE_BYTES}
- * (checked via `stat` BEFORE any bytes are read — an over-cap image never
- * touches `readRange` at all). The base64 payload rides in `_mcpImage`, a
- * field this tool's own `resultContent` consumes to build the real MCP image
- * block and then strips before the text block is serialized (see the tool
- * definition below) — no other caller should read `_mcpImage`.
- */
-async function readImageAttachment(
-  attachment: Attachment,
-  mimeType: string,
-  provider: AttachmentBytesProvider,
-): Promise<Record<string, unknown>> {
-  const stat = await statAttachmentOrMissing(attachment, provider);
-  if (stat.size > MAX_ATTACHMENT_IMAGE_BYTES) {
-    throw structuredError(
-      `Image attachment (${stat.size} bytes) exceeds the ${MAX_ATTACHMENT_IMAGE_BYTES} byte (4 MiB) read cap`,
-      {
-        error_type: "image_too_large",
-        size: stat.size,
-        max_bytes: MAX_ATTACHMENT_IMAGE_BYTES,
-        how_to: "mint a download ticket with request-attachment-download and process the image locally",
-      },
-    );
-  }
-  const raw = await provider.readRange(attachment, 0, stat.size);
-  return {
-    attachment_id: attachment.id,
-    mime_type: mimeType,
-    size_bytes: stat.size,
-    _mcpImage: { data: Buffer.from(raw).toString("base64"), mimeType },
-  };
-}
-
-/**
- * Audio/video branch: never bytes. Returns a transcript pointer built
- * entirely from metadata the transcription pipeline already stamps
- * (`attachment.metadata.transcribe_status`) plus the provider's OPTIONAL
- * sibling-note resolution — no bytes are read or even stat'd.
- */
-async function readAudioPointer(
-  attachment: Attachment,
-  provider: AttachmentBytesProvider,
-): Promise<Record<string, unknown>> {
-  const meta = attachment.metadata as Record<string, unknown> | undefined;
-  const transcribeStatus = typeof meta?.transcribe_status === "string" ? meta.transcribe_status : undefined;
-  if (!transcribeStatus) {
-    throw structuredError(`Audio/video attachment "${attachment.id}" has no transcript`, {
-      error_type: "audio_bytes_not_supported",
-      how_to:
-        "re-attach with transcribe: true to get a transcript, or mint a download ticket with request-attachment-download to process the bytes locally",
-    });
-  }
-  const result: Record<string, unknown> = {
-    attachment_id: attachment.id,
-    transcribe_status: transcribeStatus,
-    note_id: attachment.noteId,
-  };
-  if (provider.resolveTranscriptNote) {
-    const transcriptNote = await provider.resolveTranscriptNote(attachment);
-    if (transcriptNote) result.transcript_note = transcriptNote;
-  }
-  return result;
-}
-
 // ---------------------------------------------------------------------------
 // Tool generation
 // ---------------------------------------------------------------------------
@@ -455,58 +246,6 @@ export interface GenerateMcpToolsOpts {
    * path with no extra fetch.
    */
   aggregateVisibility?: (note: Note) => boolean;
-  /**
-   * `AttachmentTicketProvider` seam (vault attachment-tickets design,
-   * Wave 1 — D10 "tools omitted when unwired"). When provided,
-   * `generateMcpTools` appends `request-attachment-upload` /
-   * `request-attachment-download` to the returned tool list. Omitted (a
-   * door that hasn't wired its ticket seam yet) → the two tools are
-   * ABSENT from the list entirely — not merely erroring on call — so an
-   * agent is never shown an affordance the runtime can't back.
-   */
-  attachmentTickets?: {
-    provider: AttachmentTicketProvider;
-    /** This vault's own name — stamped onto every minted ticket so the spend route can cheaply reject a cross-vault replay. */
-    vaultName: string;
-    /**
-     * Absolute base URL for this vault's ticket spend path, no trailing
-     * slash — e.g. `https://host/vault/<name>`. A minted ticket's URL is
-     * `${urlBase}/tickets/<id>`. Resolved by the caller (server layer)
-     * from the incoming request's `X-Forwarded-Host`/proto — core stays
-     * request-unaware.
-     */
-    urlBase: string;
-    /**
-     * OPTIONAL per-note visibility predicate (tag-scope confidentiality —
-     * same intent as `expandVisibility`/`ifExistsVisible` above, kept
-     * separate because it needs to be awaitable). Both ticket tools run
-     * fully async execute() paths (unlike `expandVisibility`/
-     * `ifExistsVisible`, which feed core's SYNCHRONOUS wikilink/if_exists
-     * code and so need the shared pre-resolved-allowlist-holder
-     * machinery), so this can just be awaited inline. Omitted (unscoped /
-     * internal callers) → every note/attachment is visible.
-     */
-    noteVisible?: (note: Note) => boolean | Promise<boolean>;
-  };
-  /**
-   * `AttachmentBytesProvider` seam (Wave 2 model lane — D10, same "tools
-   * omitted when unwired" posture as `attachmentTickets` above). When
-   * provided, `generateMcpTools` appends `read-attachment` to the returned
-   * tool list. Omitted (a door that hasn't wired byte access yet) →
-   * `read-attachment` is ABSENT from the list entirely.
-   */
-  attachmentBytes?: {
-    provider: AttachmentBytesProvider;
-    /**
-     * OPTIONAL per-note visibility predicate — identical contract to
-     * `attachmentTickets.noteVisible` above (same tag-scope confidentiality
-     * intent; kept as a separate field since a caller could in principle
-     * wire one seam without the other, though the server layer always wires
-     * both from the same underlying check). Omitted → every attachment is
-     * visible.
-     */
-    noteVisible?: (note: Note) => boolean | Promise<boolean>;
-  };
 }
 
 /**
@@ -573,7 +312,7 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
     });
   };
 
-  const tools: McpToolDef[] = [
+  return [
 
     // =====================================================================
     // 1. query-notes — the universal read tool
@@ -771,7 +510,7 @@ Response shape (vault#550 — three variants, pick by what you passed):
           include_attachments: { type: "boolean", description: "Include attachment records (default: false)" },
           expand_links: { type: "boolean", description: "Inline [[wikilinks]] in returned content (default: false). Has no effect if content is not included (e.g., default list mode with include_content=false); wikilinks inside fenced or inline code are not expanded." },
           expand_depth: { type: "number", description: "Recursion depth for link expansion (default 1, max 3). Only meaningful in 'full' mode — 'summary' mode does not recurse." },
-          expand_mode: { type: "string", enum: ["full", "summary"], description: "Expansion rendering: 'full' inlines the linked note's content, 'summary' inlines metadata.summary — falling back to the note's opening paragraph when no metadata.summary exists. Default: 'full'." },
+          expand_mode: { type: "string", enum: ["full", "summary"], description: "Expansion rendering: 'full' inlines the linked note's content, 'summary' inlines only metadata.summary. Default: 'full'." },
         },
       },
       execute: async (params) => {
@@ -1880,7 +1619,7 @@ A note's response carries \`existed\` (true/false) whenever ITS \`if_exists\` wa
 - For batch: pass a \`notes\` array, each with an \`id\` field.
 - **Optimistic concurrency is required by default.** Pass \`if_updated_at\` with the \`updated_at\` value you last read — the update is rejected with a conflict error if the note has changed since. Re-read, reconcile, and retry. To skip the safety check (e.g. bulk migration), pass \`force: true\` instead; the update then runs unconditionally. \`force\` only waives the *requirement to supply* \`if_updated_at\` — if you pass both, the precondition you supplied still applies and a mismatch returns a conflict error. \`append\` / \`prepend\` only updates are exempt from the precondition (no-conflict-by-design). **Batch default (vault#554):** a top-level \`force\` and/or \`if_updated_at\` alongside a \`notes\` array applies as the DEFAULT for every item that doesn't set its own — e.g. \`{force: true, notes: [{id: "a", content: "..."}, {id: "b", content: "...", if_updated_at: "..."}]}\` forces item "a" but still enforces the precondition on item "b" (its own \`if_updated_at\` wins). Per-item values always take precedence over the top-level default.
 - **Idempotent upsert via \`if_missing: "create"\`** — when the note doesn't exist, create it from this same payload (content/path/tags/metadata become the create fields; OC precondition skipped — nothing to conflict with). Response carries \`created: true\`. Useful for nightly sync loops that don't know ahead of time whether the note exists. Default \`"fail"\` (current behavior — missing note errors). See vault#309.
-- \`include_content\` (default \`true\`) — set \`false\` to receive a lean index shape (\`id\`, \`path\`, \`createdAt\`, \`updatedAt\`, \`createdBy\`, \`createdVia\`, \`lastUpdatedBy\`, \`lastUpdatedVia\`, \`tags\`, \`metadata\`, \`byteSize\`, \`preview\`, \`displayTitle\`) instead of full content. Useful for agents making frequent small edits to large notes (e.g. via \`append\` or \`content_edit\`) where re-receiving the body is the dominant cost. \`validation_status\` is preserved on the lean shape when present. \`displayTitle\` is the note's first non-empty content line (heading markers stripped, ~120 chars max), \`null\` when content is empty — never stored, computed fresh from content already in hand.
+- \`include_content\` (default \`true\`) — set \`false\` to receive a lean index shape (\`id\`, \`path\`, \`createdAt\`, \`updatedAt\`, \`createdBy\`, \`createdVia\`, \`lastUpdatedBy\`, \`lastUpdatedVia\`, \`tags\`, \`metadata\`, \`byteSize\`, \`preview\`) instead of full content. Useful for agents making frequent small edits to large notes (e.g. via \`append\` or \`content_edit\`) where re-receiving the body is the dominant cost. \`validation_status\` is preserved on the lean shape when present.
 
 Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\` (the principal + interface of the first write) and \`lastUpdatedBy\`/\`lastUpdatedVia\` (the most recent write). NULL on notes written before attribution existed. Filter on them with \`created_by\`/\`last_updated_by\`/\`created_via\`/\`last_updated_via\`.`,
       inputSchema: {
@@ -1954,7 +1693,7 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
           },
           include_content: {
             type: "boolean",
-            description: "Response shape opt-out. Default `true` (returns the full Note with content). Set `false` to receive the lean index shape (drops `content`, adds `byteSize`, a whitespace-collapsed `preview`, and a computed `displayTitle`). `validation_status` is preserved on the lean shape when present. Applies uniformly to single and batch responses.",
+            description: "Response shape opt-out. Default `true` (returns the full Note with content). Set `false` to receive the lean index shape (drops `content`, adds `byteSize` and a whitespace-collapsed `preview`). `validation_status` is preserved on the lean shape when present. Applies uniformly to single and batch responses.",
           },
           include_links: {
             type: "boolean",
@@ -3040,316 +2779,6 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
     },
 
   ];
-
-  // =====================================================================
-  // 12/13. request-attachment-upload / request-attachment-download —
-  // runtime-lane attachment tickets (Wave 1). Present ONLY when the
-  // server layer wires an AttachmentTicketProvider — see
-  // `GenerateMcpToolsOpts.attachmentTickets`'s doc comment (D10, "tools
-  // omitted when unwired"). Bytes never pass through either tool: the
-  // model gets back a URL + a literal curl_example; a runtime with a
-  // shell spends it directly, outside this MCP session entirely.
-  // =====================================================================
-  const ticketSeam = opts?.attachmentTickets;
-  if (ticketSeam) {
-    tools.push(
-      {
-        name: "request-attachment-upload",
-        requiredVerb: "write",
-        description:
-          "Mint a short-lived, single-use upload URL for a note attachment. Bytes never pass through this tool — you get back a URL (+ a ready-to-run `curl_example`) your runtime's shell spends directly; no MCP session credential is needed to spend it. Provide the target `note` (id or path), the `filename`, and its exact `size_bytes` — declared here and enforced at spend (a mismatch, or exceeding the 100 MiB REST upload cap, fails the mint or the upload). `mime_type` is inferred from the filename's extension when omitted. Pass `transcribe: true` for an audio file to enqueue it exactly like the REST attach flow does. The ticket's `expires_at` scales with declared size (10 minutes base + 10s per MiB, capped at 30 minutes) and can be spent exactly once — a failed curl means re-minting, not retrying the same URL.",
-        inputSchema: {
-          type: "object",
-          properties: {
-            note: { type: "string", description: "Target note ID or path" },
-            filename: { type: "string", description: "Original filename — sanitized for a blocked extension (active-content types: .html/.svg/.xml/.js/.css/…) and used to infer the MIME type when `mime_type` is omitted." },
-            size_bytes: {
-              type: "number",
-              description: `Declared upload size in bytes. Must be > 0 and <= ${MAX_TICKET_UPLOAD_BYTES} (100 MiB — the same ceiling REST's own /storage/upload enforces). The spend endpoint rejects (413) any upload that exceeds this declared size.`,
-            },
-            mime_type: { type: "string", description: "MIME type to store on the attachment row. Inferred from `filename`'s extension when omitted (`application/octet-stream` for an uncurated extension)." },
-            transcribe: { type: "boolean", description: "Opt into transcription for an audio attachment — mirrors the REST `POST /notes/:id/attachments` `transcribe` flag." },
-          },
-          required: ["note", "filename", "size_bytes"],
-        },
-        execute: async (params) => {
-          const noteRef = params.note;
-          if (typeof noteRef !== "string" || noteRef.trim() === "") {
-            throw structuredError("`note` is required", {
-              error_type: "missing_required_field",
-              field: "note",
-              how_to: "pass the target note's id or path",
-            });
-          }
-          const filename = params.filename;
-          if (typeof filename !== "string" || filename.trim() === "") {
-            throw structuredError("`filename` is required", {
-              error_type: "missing_required_field",
-              field: "filename",
-              how_to: "pass the original filename you're about to upload",
-            });
-          }
-          const sizeBytes = params.size_bytes;
-          if (typeof sizeBytes !== "number" || !Number.isFinite(sizeBytes) || sizeBytes <= 0) {
-            throw structuredError("`size_bytes` must be a positive number", {
-              error_type: "invalid_query",
-              field: "size_bytes",
-              how_to: "pass the exact byte length of the file you're about to upload",
-            });
-          }
-          if (sizeBytes > MAX_TICKET_UPLOAD_BYTES) {
-            throw structuredError(
-              `size_bytes (${sizeBytes}) exceeds the ${MAX_TICKET_UPLOAD_BYTES} byte (100 MiB) upload cap`,
-              {
-                error_type: "file_too_large",
-                field: "size_bytes",
-                limit: MAX_TICKET_UPLOAD_BYTES,
-                got: sizeBytes,
-                how_to: "REST /storage/upload shares this same 100 MiB ceiling — split the file or upload it out-of-band",
-              },
-            );
-          }
-
-          const note = requireNote(db, noteRef);
-          if (ticketSeam.noteVisible && !(await ticketSeam.noteVisible(note))) {
-            // Uniform not_found — a tag-scoped caller learns nothing about
-            // an out-of-scope note's existence (same posture as every other
-            // scope-gated tool in this file).
-            throw structuredError(`Note not found: "${noteRef}"`, { error_type: "not_found", field: "note" });
-          }
-
-          const ext = sanitizeAttachmentExtension(filename);
-          if (BLOCKED_ATTACHMENT_EXTENSIONS.has(ext)) {
-            throw structuredError(`File type ${ext} not allowed (active/executable content)`, {
-              error_type: "blocked_upload_extension",
-              field: "filename",
-              extension: ext,
-              how_to: "rename with a non-executable extension, or store the content as note text instead",
-            });
-          }
-
-          const mimeType =
-            typeof params.mime_type === "string" && params.mime_type.trim() !== ""
-              ? params.mime_type
-              : mimeForAttachmentExtension(ext);
-
-          const now = Date.now();
-          const expiresAt = now + computeTicketTtlMs(sizeBytes);
-          const id = generateTicketId();
-          const ticket: AttachmentTicket = {
-            id,
-            kind: "upload",
-            vaultName: ticketSeam.vaultName,
-            createdAt: now,
-            expiresAt,
-            noteId: note.id,
-            filename,
-            mimeType,
-            sizeBytes,
-            transcribe: params.transcribe === true,
-          };
-          await ticketSeam.provider.put(ticket);
-
-          const url = `${ticketSeam.urlBase}/tickets/${id}`;
-          return {
-            method: "PUT",
-            url,
-            headers: { "content-type": mimeType },
-            expires_at: new Date(expiresAt).toISOString(),
-            max_bytes: sizeBytes,
-            curl_example: `curl -X PUT -H 'content-type: ${mimeType}' --data-binary @${filename} '${url}'`,
-          };
-        },
-      },
-      {
-        name: "request-attachment-download",
-        requiredVerb: "read",
-        description:
-          "Mint a short-lived, single-use download URL for an existing attachment's bytes. Bytes never pass through this tool — you get back a URL (+ a ready-to-run `curl_example`) your runtime's shell spends directly; no MCP session credential is needed to spend it. Pass the `attachment_id` from a note's `include_attachments: true` rows (query-notes) or `GET .../attachments`. The ticket's `expires_at` follows the same size-scaled window as upload tickets (10 minutes base, up to 30) and can be spent exactly once.",
-        inputSchema: {
-          type: "object",
-          properties: {
-            attachment_id: { type: "string", description: "The attachment's id (from a note's attachment rows)" },
-          },
-          required: ["attachment_id"],
-        },
-        execute: async (params) => {
-          const attachmentId = params.attachment_id;
-          if (typeof attachmentId !== "string" || attachmentId.trim() === "") {
-            throw structuredError("`attachment_id` is required", {
-              error_type: "missing_required_field",
-              field: "attachment_id",
-              how_to: "pass the attachment id from a note's attachment rows",
-            });
-          }
-
-          const attachment = await store.getAttachment(attachmentId);
-          if (!attachment) {
-            throw structuredError(`Attachment not found: "${attachmentId}"`, {
-              error_type: "not_found",
-              field: "attachment_id",
-            });
-          }
-
-          if (ticketSeam.noteVisible) {
-            const owningNote = await store.getNote(attachment.noteId);
-            // A missing owning note (shouldn't happen — ON DELETE CASCADE —
-            // but never trust it) collapses to the same not_found as an
-            // out-of-scope note: no oracle either way.
-            if (!owningNote || !(await ticketSeam.noteVisible(owningNote))) {
-              throw structuredError(`Attachment not found: "${attachmentId}"`, {
-                error_type: "not_found",
-                field: "attachment_id",
-              });
-            }
-          }
-
-          const metaSize = attachment.metadata?.size;
-          const declaredSize = typeof metaSize === "number" ? metaSize : undefined;
-          const now = Date.now();
-          const expiresAt = now + computeTicketTtlMs(declaredSize);
-          const id = generateTicketId();
-          const ticket: AttachmentTicket = {
-            id,
-            kind: "download",
-            vaultName: ticketSeam.vaultName,
-            createdAt: now,
-            expiresAt,
-            attachmentId: attachment.id,
-            mimeType: attachment.mimeType,
-            sizeBytes: declaredSize,
-          };
-          await ticketSeam.provider.put(ticket);
-
-          const url = `${ticketSeam.urlBase}/tickets/${id}`;
-          return {
-            method: "GET",
-            url,
-            mime_type: attachment.mimeType,
-            ...(declaredSize !== undefined ? { size_bytes: declaredSize } : {}),
-            expires_at: new Date(expiresAt).toISOString(),
-            curl_example: `curl -o downloaded${sanitizeAttachmentExtension(attachment.path) || ""} '${url}'`,
-          };
-        },
-      },
-    );
-  }
-
-  // =====================================================================
-  // 14. read-attachment — model-lane byte reads (Wave 2). Present ONLY
-  // when the server layer wires an AttachmentBytesProvider — see
-  // `GenerateMcpToolsOpts.attachmentBytes`'s doc comment (D10). Dispatches
-  // by mime family: text ranges come back as `content`/`content_offset`/
-  // `content_total_length`/`content_next_offset` (the exact query-notes
-  // pagination contract); images come back as a real MCP image block (see
-  // this tool's `resultContent`); audio/video never send bytes — a
-  // transcript pointer instead; PDF/other binary refuse with a
-  // download-ticket pointer. Unlike the ticket tools, bytes (or a base64
-  // encoding of them) DO pass through this tool — that's the whole point
-  // of the model lane.
-  // =====================================================================
-  const bytesSeam = opts?.attachmentBytes;
-  if (bytesSeam) {
-    tools.push({
-      name: "read-attachment",
-      requiredVerb: "read",
-      description:
-        "Read an attachment's content directly into this conversation (the model lane — bytes DO pass through this tool, unlike request-attachment-upload/download). Behavior depends on mime type: text/* (+ json/ndjson/yaml — csv/markdown are already text/*) returns a byte-windowed `content` slice using the exact query-notes content_offset/content_length/content_next_offset pagination contract (default 65536 bytes / 64 KiB, max 262144 / 256 KiB per call — loop, feeding content_next_offset back as content_offset, for more). image/* returns a real image you can see, capped at 4 MiB raw (over-cap refuses with a pointer to request-attachment-download; content_offset/content_length don't apply to images). audio/video never send bytes — you get back a transcript pointer (transcribe_status, note_id, and a transcript_note when one exists) instead of the audio itself. PDF and other binary formats aren't directly readable here — mint a download ticket with request-attachment-download and process the file with your own runtime.",
-      inputSchema: {
-        type: "object",
-        properties: {
-          attachment_id: {
-            type: "string",
-            description: "The attachment's id (from a note's attachment rows, e.g. include_attachments: true on query-notes)",
-          },
-          content_offset: {
-            type: "number",
-            description: "Text attachments only. Byte offset to start reading from (UTF-8 bytes). Defaults to 0.",
-          },
-          content_length: {
-            type: "number",
-            description: "Text attachments only. Byte budget for this call. Defaults to 65536 (64 KiB); max 262144 (256 KiB).",
-          },
-        },
-        required: ["attachment_id"],
-      },
-      execute: async (params) => {
-        const attachmentId = params.attachment_id;
-        if (typeof attachmentId !== "string" || attachmentId.trim() === "") {
-          throw structuredError("`attachment_id` is required", {
-            error_type: "missing_required_field",
-            field: "attachment_id",
-            how_to: "pass the attachment id from a note's attachment rows",
-          });
-        }
-
-        const attachment = await store.getAttachment(attachmentId);
-        if (!attachment) {
-          throw structuredError(`Attachment not found: "${attachmentId}"`, {
-            error_type: "not_found",
-            field: "attachment_id",
-          });
-        }
-
-        if (bytesSeam.noteVisible) {
-          const owningNote = await store.getNote(attachment.noteId);
-          // Same uniform not_found posture as the ticket tools — a
-          // tag-scoped caller learns nothing about an out-of-scope note's
-          // existence via a differential error.
-          if (!owningNote || !(await bytesSeam.noteVisible(owningNote))) {
-            throw structuredError(`Attachment not found: "${attachmentId}"`, {
-              error_type: "not_found",
-              field: "attachment_id",
-            });
-          }
-        }
-
-        const mimeType = effectiveAttachmentMime(attachment);
-
-        if (isImageMime(mimeType)) {
-          if (params.content_offset !== undefined || params.content_length !== undefined) {
-            throw structuredError("content_offset/content_length don't apply to image attachments", {
-              error_type: "invalid_query",
-              field: "content_offset",
-              hint: "omit content_offset/content_length for an image read — the whole image (up to the 4 MiB cap) comes back in one call",
-            });
-          }
-          return await readImageAttachment(attachment, mimeType, bytesSeam.provider);
-        }
-        if (isTextMime(mimeType)) {
-          return await readTextAttachment(attachment, mimeType, params, bytesSeam.provider);
-        }
-        if (isAudioOrVideoMime(mimeType)) {
-          return await readAudioPointer(attachment, bytesSeam.provider);
-        }
-
-        // Other binary (PDF, zip, docx, ...) — refuse honestly rather than
-        // returning garbage or truncated bytes; extraction is a v2 concern
-        // (D5). Still stats first so a row whose bytes are ALSO gone gets
-        // the more accurate attachment_binary_missing instead.
-        const stat = await statAttachmentOrMissing(attachment, bytesSeam.provider);
-        throw structuredError(`Attachment type "${mimeType}" isn't directly readable by this tool`, {
-          error_type: "unsupported_attachment_type",
-          mime_type: mimeType,
-          size: stat.size,
-          how_to: "mint a download ticket with request-attachment-download and process the file locally",
-        });
-      },
-      resultContent: (result) => {
-        const r = result as ({ _mcpImage?: { data: string; mimeType: string } } & Record<string, unknown>) | null;
-        if (r && r._mcpImage) {
-          const { _mcpImage, ...rest } = r;
-          return [
-            { type: "text", text: JSON.stringify(rest, null, 2) },
-            { type: "image", data: _mcpImage.data, mimeType: _mcpImage.mimeType },
-          ];
-        }
-        return [{ type: "text", text: JSON.stringify(result, null, 2) }];
-      },
-    });
-  }
-
-  return tools;
 }
 
 // ---------------------------------------------------------------------------