@openparachute/vault 0.7.3-rc.6 → 0.7.3-rc.8

package/core/src/display-title.test.ts

@@ -83,6 +83,47 @@ describe("computeDisplayTitle", () => {
     const result = computeDisplayTitle(emojiTitle)!;
     expect(Array.from(result).length).toBe(DISPLAY_TITLE_MAX_LEN);
   });
+
+  describe("leading frontmatter block (misuse path — direct create with raw frontmatter)", () => {
+    it("skips a closed frontmatter block and derives the first line of the DOCUMENT", () => {
+      expect(computeDisplayTitle("---\ntitle: X\n---\n# Real Title")).toBe("Real Title");
+    });
+
+    it("skips a closed frontmatter block with multiple fields + blank lines after", () => {
+      expect(
+        computeDisplayTitle("---\ntitle: X\ntags: [a, b]\n---\n\n\nReal Title\nbody"),
+      ).toBe("Real Title");
+    });
+
+    it("falls back to treating an UNTERMINATED opening `---` as ordinary content", () => {
+      // No closing fence anywhere in the content — a note whose real first
+      // line is literally "---" (e.g. a markdown horizontal rule opener)
+      // must not be mangled.
+      expect(computeDisplayTitle("---\nnot frontmatter, just a rule\nmore text")).toBe("---");
+    });
+
+    it("returns null when content is EXACTLY a closed frontmatter block (nothing after)", () => {
+      expect(computeDisplayTitle("---\ntitle: X\n---\n")).toBeNull();
+      expect(computeDisplayTitle("---\ntitle: X\n---")).toBeNull();
+    });
+
+    it("returns null when only blank lines follow a closed frontmatter block", () => {
+      expect(computeDisplayTitle("---\ntitle: X\n---\n\n  \n")).toBeNull();
+    });
+
+    it("does not treat a closing fence found past the bounded scan window as a frontmatter close", () => {
+      // Opening `---` with the closing fence past FRONTMATTER_SCAN_LINES
+      // (100): the scan gives up and falls back to ordinary-content
+      // behavior, deriving from line 0.
+      const filler = Array.from({ length: 150 }, (_, i) => `line ${i}`).join("\n");
+      expect(computeDisplayTitle(`---\n${filler}\n---\nReal Title`)).toBe("---");
+    });
+
+    it("normal content with no leading `---` is byte-identical to prior behavior", () => {
+      expect(computeDisplayTitle("# Grocery List\nmilk, eggs")).toBe("Grocery List");
+      expect(computeDisplayTitle("Just a note\nbody text")).toBe("Just a note");
+    });
+  });
 });
 
 describe("toNoteIndex — displayTitle wiring", () => {

package/core/src/mcp.ts

@@ -45,6 +45,18 @@ import {
   contentRangeRequiresContent,
   MIN_CONTENT_LENGTH,
 } from "./content-range.js";
+import {
+  BLOCKED_ATTACHMENT_EXTENSIONS,
+  sanitizeAttachmentExtension,
+  mimeForAttachmentExtension,
+} from "./attachment/policy.js";
+import {
+  computeTicketTtlMs,
+  generateTicketId,
+  MAX_TICKET_UPLOAD_BYTES,
+  type AttachmentTicket,
+  type AttachmentTicketProvider,
+} from "./attachment/tickets.js";
 
 export interface McpToolDef {
   name: string;
@@ -80,7 +92,7 @@ export interface McpToolDef {
  */
 function structuredError(
   message: string,
-  fields: { error_type: string; field?: string; hint?: string },
+  fields: { error_type: string; field?: string; hint?: string } & Record<string, unknown>,
 ): Error {
   return Object.assign(new Error(message), fields);
 }
@@ -246,6 +258,39 @@ 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>;
+  };
 }
 
 /**
@@ -312,7 +357,7 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
     });
   };
 
-  return [
+  const tools: McpToolDef[] = [
 
     // =====================================================================
     // 1. query-notes — the universal read tool
@@ -2779,6 +2824,202 @@ 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}'`,
+          };
+        },
+      },
+    );
+  }
+
+  return tools;
 }
 
 // ---------------------------------------------------------------------------

package/core/src/notes.ts

@@ -2769,6 +2769,15 @@ export const NOTE_INDEX_PREVIEW_LEN = 120;
 /** Max code points in a computed `displayTitle` (title axis, ratified 2026-07-17). */
 export const DISPLAY_TITLE_MAX_LEN = 120;
 
+/**
+ * Bounded line-count a leading frontmatter block's closing fence is
+ * searched within (see `computeDisplayTitle`). Frontmatter blocks are a
+ * handful of lines in practice; capping the scan keeps a pathological
+ * "content starts with `---` but never closes it" note O(1)-ish rather
+ * than a full-content scan on every derivation.
+ */
+const FRONTMATTER_SCAN_LINES = 100;
+
 /**
  * Derive a note's display title: the first non-empty line of `content`,
  * with a leading markdown heading marker (`#` through `######`) and its
@@ -2783,11 +2792,33 @@ export const DISPLAY_TITLE_MAX_LEN = 120;
  * in place of a `null` title — is deliberately NOT this function's job; it
  * reports the honest content-derived value (or its absence) and leaves
  * rendering to the caller.
+ *
+ * Frontmatter skip: normal ingestion strips a YAML frontmatter block into
+ * `metadata` before create, so `content` never carries one — but a direct
+ * MCP/REST create can paste raw frontmatter-bearing text
+ * (`---\ntitle: X\n---\n# Real Title`), and the first line of that
+ * DOCUMENT is not the first line of its delimiter. When `content` opens
+ * with a `---` line, derivation starts after the matching CLOSING `---`
+ * (searched within the first `FRONTMATTER_SCAN_LINES` lines). An
+ * unterminated opening `---` falls back to the pre-existing behavior —
+ * scanning from line 0 — so a note whose real first line is literally
+ * `---` isn't mangled.
  */
 export function computeDisplayTitle(content: string | null | undefined): string | null {
   if (!content) return null;
-  for (const rawLine of content.split("\n")) {
-    const stripped = rawLine.replace(/^#{1,6}\s*/, "").trim();
+  const lines = content.split("\n");
+  let startIndex = 0;
+  if (lines[0]?.trim() === "---") {
+    const scanLimit = Math.min(lines.length, FRONTMATTER_SCAN_LINES);
+    for (let i = 1; i < scanLimit; i++) {
+      if (lines[i]?.trim() === "---") {
+        startIndex = i + 1;
+        break;
+      }
+    }
+  }
+  for (let i = startIndex; i < lines.length; i++) {
+    const stripped = lines[i]!.replace(/^#{1,6}\s*/, "").trim();
     if (stripped === "") continue;
     // Iterate by Unicode code points so we don't split surrogate pairs mid-character.
     const codePoints = Array.from(stripped);

package/core/src/search-title-boost.test.ts

@@ -104,4 +104,22 @@ describe("search title-boost", () => {
     const hits = await store.searchNotes("nonexistent_term_xyz");
     expect(hits).toEqual([]);
   });
+
+  it("boosts on the post-frontmatter title line, not the `---` delimiter (shares computeDisplayTitle's frontmatter skip)", async () => {
+    // Direct-create misuse path: raw frontmatter-bearing content. Without
+    // the frontmatter skip, the derived "title" would be the literal
+    // string "---", which never matches any query term, so this note
+    // would wrongly land in the body-only tier.
+    await store.createNote(
+      "---\ntitle: irrelevant\n---\n# Budget Review\nQ3 numbers",
+      { path: "frontmatter-led" },
+    );
+    await store.createNote(
+      "Weekly Standup\nsomewhere we discuss the budget in passing",
+      { path: "body-only" },
+    );
+
+    const hits = await store.searchNotes("budget review");
+    expect(hits[0].path).toBe("frontmatter-led");
+  });
 });

package/core/src/vault-projection.ts

@@ -272,6 +272,42 @@ function sqliteToUserType(t: string): string {
   return t.toLowerCase();
 }
 
+// ---------------------------------------------------------------------------
+// Attachments orientation block (attachment-tickets design, Wave 0+1)
+// ---------------------------------------------------------------------------
+
+/**
+ * The Attachments orientation block, rendered into the connect-time
+ * markdown brief (`projectionToMarkdown`) so every agent learns, every
+ * session, how to move file bytes into/out of this vault without spending
+ * its own context on them (bytes never ride MCP either way).
+ *
+ * `ticketsEnabled` reflects whether THIS door has wired an
+ * `AttachmentTicketProvider` (bun: always, as of this PR; cloud: not yet
+ * — its mirror is a separate PR). An unwired door omits BOTH the ticket
+ * tools from `tools/list` (see `generateMcpTools`'s `attachmentTickets`
+ * opt) AND the ticket-tool sentences here — the brief never dangles a
+ * pointer at a tool the agent can't actually call.
+ *
+ * Kept as a single dense paragraph (not its own multi-line list) to stay
+ * inside the connect-time brief's token budget — see
+ * `projectionToMarkdown`'s doc comment.
+ */
+export function attachmentsInstructionBlock(opts: { ticketsEnabled: boolean }): string {
+  const sentences: string[] = [
+    "Notes can carry file attachments (`include_attachments: true` on `query-notes` returns their rows; bytes don't ride MCP).",
+  ];
+  if (opts.ticketsEnabled) {
+    sentences.push(
+      "To move bytes, call `request-attachment-upload` / `request-attachment-download` — each mints a short-lived, single-use URL (with a ready-to-run `curl_example`) your shell spends directly; no MCP session credential is needed to spend it.",
+    );
+  }
+  sentences.push(
+    "If your runtime holds this vault's own API token, REST works too: upload = `POST {base}/storage/upload` (multipart `file`, ≤100 MB) then `POST {base}/notes/{id}/attachments` `{path, mimeType, transcribe?}`; download = `GET {base}/storage/{path}` with the same `Authorization: Bearer`. Audio attached with `transcribe: true` is transcribed automatically.",
+  );
+  return sentences.join(" ");
+}
+
 // ---------------------------------------------------------------------------
 // Markdown rendering — for getServerInstruction
 // ---------------------------------------------------------------------------
@@ -302,6 +338,13 @@ export function projectionToMarkdown(args: {
    * known and always surfaced. See `chooseHubOrigin` (src/mcp-install.ts).
    */
   coordinates?: { hubOrigin: string; hubOriginKnown: boolean };
+  /**
+   * Attachments orientation (see `attachmentsInstructionBlock`). Omitted
+   * defaults to `{ ticketsEnabled: false }` — safe-by-default so a caller
+   * that hasn't wired ticket support yet (or a test fixture) never
+   * accidentally advertises tools it can't back.
+   */
+  attachments?: { ticketsEnabled: boolean };
 }): string {
   const { vaultName, description, projection, coordinates } = args;
   const stats = projection.stats;
@@ -418,6 +461,11 @@ export function projectionToMarkdown(args: {
   lines.push("");
   lines.push("If schema or tags change during this session, call `vault-info` to refresh the full projection. Call `list-tags { include_schema: true }` for tag-only details.");
 
+  lines.push("");
+  lines.push("## Attachments");
+  lines.push("");
+  lines.push(attachmentsInstructionBlock(args.attachments ?? { ticketsEnabled: false }));
+
   // Scripting pointer block: the connect-time brief used to dead-end on
   // querying — an agent had no path to "how do I script/automate against this
   // vault." Point at the guide rather than inlining it, to keep this brief

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/vault",
-  "version": "0.7.3-rc.6",
+  "version": "0.7.3-rc.8",
   "description": "Agent-native knowledge graph. Notes, tags, links over MCP.",
   "module": "src/cli.ts",
   "type": "module",