@llamaventures/cli 1.16.0 → 1.17.0

package/AGENT_BRIEFING.md

@@ -82,9 +82,9 @@ HTML / thesis / artifact in hand
   └──────────────┬──────────────────────────────────┘
                  │
         yes ────►│  → Llama Command DEAL page
-                 │    `llama html upload <dealId> --new --title "..." --file <path>`
+                 │    `llama html publish <deal-id-or-name> --file <path> --title "..."`
                  │    Renders at /deals/<id>/browse/<slug>.
-                 │    Use --doc <slug> + --file to update an existing one.
+                 │    Use --doc <slug> or --update when updating an existing one.
                  │
         no  ────►│  Is it cross-deal / institutional knowledge?
                  │   (sector landscape · market map · framework · firm-level
@@ -138,7 +138,7 @@ The table below details the exact CLI for each destination.
 |---|---|---|
 | Deal metadata (status, stage, valuation, founders, notes, etc.) | Pipeline (Postgres) | `llama deal create` / `llama deal update` |
 | Brief blocks (text / link / embed / callout) | Pipeline | `llama brief add-text` / `add-link` / `add-callout` |
-| **HTML artifact, internal — IC report, dashboard, market map, 2×2, any hand-authored page** | **Llama Command native** (Postgres + sandboxed iframe at `/deals/<id>/browse/<slug>`) | Default path when the user says "deploy to llama", "deploy to llama command", "部署到 llama command", "put this HTML on the deal page", "在 deal 里看这个". **You MUST declare intent — "new artifact" vs "update existing":**<br><br>**New artifact:** `llama html upload <dealId> --new --title "<artifact name>" --file <path>` (CLI slugifies the title; pass `--doc <slug>` to override).<br>**Update existing:** `llama html upload <dealId> --doc <slug> --file <path>` (slug must already exist — run `llama html docs <dealId>` first to see what's there).<br><br>The bare form `llama html upload <id> --file <path>` REFUSES if `main` already has content. Do NOT default to Netlify for internal pages. |
+| **HTML artifact, internal — IC report, dashboard, market map, 2×2, any hand-authored page** | **Llama Command native** (Postgres + sandboxed iframe at `/deals/<id>/browse/<slug>`) | Default path when the user says "deploy to llama", "deploy to llama command", "部署到 llama command", "put this HTML on the deal page", "在 deal 里看这个". **Preferred agent-safe path:** `llama html publish <deal-id-or-name> --file <path> --title "<artifact name>" [--doc <slug>]`. It resolves deal names, avoids silent overwrite, auto-detects sibling asset folders, uploads, then verifies by reading the version back.<br><br>Low-level explicit path remains available: new artifact `llama html upload <dealId> --new --title "<artifact name>" --file <path>`; update existing `llama html upload <dealId> --doc <slug> --file <path>`.<br><br>Never paste large HTML into chat or MCP tool arguments. Use file paths. Do NOT default to Netlify for internal pages. |
 | HTML artifact, external — founder-facing share link | Netlify | Only when the user explicitly says "share link", "give it to the founder", "publish publicly". Use the `netlify-access-guard` workflow (server-side password + edge 401 verification). |
 | Insights, decisions, framework improvements | Wiki (markdown) | `llama wiki save <slug> --content "..."` (with attribution — see below) |
 | **HTML wiki entry — standalone HTML page hosted at `/wiki/<slug>`** (sector landscape, market map, dashboard, hand-styled thesis page) | **Wiki (HTML)** | `llama wiki save <slug> --title "..." --file <path.html> --sources "..."`. Auto-detects content_type=html from extension. Public page is full-viewport sandboxed iframe takeover (no wiki chrome). Sources/status/title still required; appears in `wiki search` + backlinks. Use when the user says "deploy this HTML to wiki", "wiki 词条", "make this page a wiki entry". HTML must be self-contained (inline CSS/JS, image data URIs or external URLs) — asset bundles aren't supported on wiki yet. **Native comments + working in-page (#) anchor links are injected automatically** — readers discuss inline and the table of contents scrolls; you don't wire anything up (pages that already embed the comment widget are left as-is). |
@@ -229,6 +229,10 @@ llama brief add-callout <dealId> --tone insight|warning|info|success --heading "
 # Default path when user says "deploy to llama / 部署到 llama command / put this HTML on the deal page".
 # Each deal can host many slug-scoped artifacts. ALWAYS declare intent: new vs update.
 
+# Agent-safe default: pass a file path, not inline HTML.
+llama html publish "<deal name or id>" --file ./report.html --title "Consumer-Facing Thesis"
+llama html publish "<deal name or id>" --file ./report.html --doc thesis --update
+
 llama html docs <dealId>                                                 # list slugs currently on this deal
 llama html docs create <dealId> <slug> [--title "..."]                   # pre-create a slot (optional; upload --new also creates)
 llama html docs archive <dealId> <slug>                                  # soft-archive a doc
@@ -247,6 +251,11 @@ llama html restore <dealId> <version> [--doc <slug>]                     # promo
 llama html reset <dealId> [--doc <slug>]                                 # soft-delete latest (browse reverts to empty)
 
 # Safety contract (since 1.5.0):
+#  - Coding agents should use `llama html publish ... --file <path>` for memos/reports.
+#    Do not move large HTML through chat text or MCP `html_upload` string args.
+#  - Successful uploads return `sha256` and `client_upload_id`; verification
+#    reads the server copy back and compares version/bytes/sha256 when available.
+#    If a network retry is needed for the same attempt, reuse `--upload-id`.
 #  - Bare `llama html upload <id> --file X` REFUSES if 'main' already has content.
 #    The error names the existing artifact and suggests --doc main / --new --title "...".
 #  - --slug is silently accepted as an alias for --doc (agent-confusion mitigation).

package/CHANGELOG.md

@@ -6,6 +6,40 @@ this project adheres to [Semantic Versioning](https://semver.org).
 
 ## [Unreleased]
 
+## [1.17.0] - 2026-06-23
+
+### Added
+- **`llama html publish <deal-id-or-name> --file <path>`** — agent-safe
+  HTML artifact publishing for deal pages. It resolves deal names, preflights
+  file size/HTML shape, chooses a non-overwriting slug by default, auto-detects
+  sibling `*_files` asset folders, uploads, and performs read-after-write
+  verification before returning the viewer URL.
+- **`html_upload_file` MCP tool** — file-path based HTML upload for MCP-native
+  agents, including preflight checks, optional asset-folder upload, and
+  read-after-write verification.
+
+### Changed
+- HTML publishing now sends a per-attempt `client_upload_id` and verifies the
+  server copy by `sha256` when Command returns it. Retrying the same failed
+  attempt with `--upload-id` avoids duplicate versions. JSON and multipart
+  uploads also send the same id as `X-Llama-Upload-Id` so server logs and
+  retry/debug paths can correlate the attempt.
+- MCP `html_upload` now refuses inline HTML bodies over 50KB and instructs
+  agents to use `html_upload_file` or `llama html publish --file`. This avoids
+  moving large memos through model/tool-call context, the main reliability
+  failure mode for long IC memos.
+- MCP `html_upload_bundle` is now treated as a small inline fallback and refuses
+  tool-call payloads over 50KB. Agents should use `html_upload_file` with
+  `assetsDir` or `llama html publish --file --assets` for saved-page exports.
+- `AGENT_BRIEFING.md` now teaches coding agents to use file-path based HTML
+  publishing as the default Llama Command route.
+- Top-level CLI help now routes deal-specific HTML artifacts to `llama html
+  publish --file` instead of the lower-level upload command.
+- Local-agent telemetry now redacts content payload fields such as `html`,
+  `body`, `content`, `markdown`, `message`, and `text`, keeping only
+  chars/bytes/sha256. Incident-sized memo uploads remain observable without
+  storing memo text in the telemetry stream.
+
 ## [1.16.0] - 2026-06-22
 
 ### Added
@@ -423,7 +457,21 @@ assistant-drafted (🤖) and enforces the AI trust ceiling.
 
 ---
 
-[Unreleased]: https://github.com/Llama-Ventures/llama-cli/compare/v1.3.1...HEAD
+[Unreleased]: https://github.com/Llama-Ventures/llama-cli/compare/v1.17.0...HEAD
+[1.17.0]: https://github.com/Llama-Ventures/llama-cli/compare/v1.16.0...v1.17.0
+[1.16.0]: https://github.com/Llama-Ventures/llama-cli/compare/v1.15.1...v1.16.0
+[1.15.1]: https://github.com/Llama-Ventures/llama-cli/compare/v1.15.0...v1.15.1
+[1.15.0]: https://github.com/Llama-Ventures/llama-cli/compare/v1.14.1...v1.15.0
+[1.14.1]: https://github.com/Llama-Ventures/llama-cli/compare/v1.14.0...v1.14.1
+[1.14.0]: https://github.com/Llama-Ventures/llama-cli/compare/v1.13.0...v1.14.0
+[1.13.0]: https://github.com/Llama-Ventures/llama-cli/compare/v1.12.0...v1.13.0
+[1.12.0]: https://github.com/Llama-Ventures/llama-cli/compare/v1.11.0...v1.12.0
+[1.11.0]: https://github.com/Llama-Ventures/llama-cli/compare/v1.10.0...v1.11.0
+[1.10.0]: https://github.com/Llama-Ventures/llama-cli/compare/v1.7.0...v1.10.0
+[1.7.0]: https://github.com/Llama-Ventures/llama-cli/compare/v1.5.0...v1.7.0
+[1.5.0]: https://github.com/Llama-Ventures/llama-cli/compare/v1.4.4...v1.5.0
+[1.4.4]: https://github.com/Llama-Ventures/llama-cli/compare/v1.4.0...v1.4.4
+[1.4.0]: https://github.com/Llama-Ventures/llama-cli/compare/v1.3.1...v1.4.0
 [1.3.1]: https://github.com/Llama-Ventures/llama-cli/compare/v1.3.0...v1.3.1
 [1.3.0]: https://github.com/Llama-Ventures/llama-cli/compare/v1.2.4...v1.3.0
 [1.2.4]: https://github.com/Llama-Ventures/llama-cli/compare/v1.2.3...v1.2.4

package/bin/llama-mcp.mjs

@@ -8,11 +8,13 @@
 // CLI: gcloud (preferred) → $LLAMA_TOKEN → ~/.llama/token.
 
 import { createRequire } from "module";
+import { randomUUID } from "crypto";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import {
   getAuthHeaders,
+  getBaseUrl,
   getLastAgentEvent,
   readBriefing,
   request,
@@ -32,13 +34,26 @@ import {
 
 setClientRuntime({ client: "mcp" });
 
+function newHtmlUploadId() {
+  return `mcp-${randomUUID()}`;
+}
+
+function normalizeUploadId(value) {
+  if (typeof value !== "string" || !value.trim()) return null;
+  const id = value.trim();
+  if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(id)) {
+    throw new Error("clientUploadId must be 1-128 chars: letters, numbers, dot, underscore, colon, or hyphen");
+  }
+  return id;
+}
+
 // Wrap a request() call into the MCP CallToolResult shape. Catches errors
 // (NO_AUTH / 401 / 5xx / network) and surfaces them as `isError: true`
 // content so the calling agent sees a clean error string instead of the
 // MCP transport closing.
-async function callApi(method, path, body) {
+async function callApi(method, path, body, opts = {}) {
   try {
-    const result = await request(method, path, body);
+    const result = await request(method, path, body, opts);
     const text = typeof result === "string" ? result : JSON.stringify(result, null, 2);
     return { content: [{ type: "text", text }] };
   } catch (err) {
@@ -56,6 +71,10 @@ function textResult(text, isError = false) {
   };
 }
 
+function jsonResult(value, isError = false) {
+  return textResult(JSON.stringify(value, null, 2), isError);
+}
+
 function splitSources(value) {
   if (Array.isArray(value)) return value.filter(Boolean);
   if (!value || value === true) return undefined;
@@ -1379,17 +1398,230 @@ server.registerTool(
 // All html_* tools take an optional documentSlug param. Default 'main'.
 // Each deal can hold multiple named documents (different HTMLs); use
 // html_docs_list to discover slugs.
+const INLINE_HTML_UPLOAD_LIMIT = 50 * 1024;
+const MAX_HTML_BYTES = 5 * 1024 * 1024;
+const MAX_ASSET_BYTES = 50 * 1024 * 1024;
+const MAX_BUNDLE_BYTES = 100 * 1024 * 1024;
+
 function htmlUrl(dealId, slug) {
   return `/api/deals/${encodeURIComponent(dealId)}/documents/${encodeURIComponent(slug ?? "main")}/html`;
 }
 
+function looksLikeHtml(html) {
+  const head = String(html || "").trim().slice(0, 256).toLowerCase();
+  return head.startsWith("<!doctype html") || head.startsWith("<html");
+}
+
+function mimeForAsset(path) {
+  const ext = (String(path).split(".").pop() || "").toLowerCase();
+  return (
+    {
+      jpg: "image/jpeg",
+      jpeg: "image/jpeg",
+      png: "image/png",
+      gif: "image/gif",
+      webp: "image/webp",
+      svg: "image/svg+xml",
+      ico: "image/x-icon",
+      avif: "image/avif",
+      css: "text/css",
+      js: "text/javascript",
+      json: "application/json",
+      woff: "font/woff",
+      woff2: "font/woff2",
+      ttf: "font/ttf",
+      otf: "font/otf",
+      mp4: "video/mp4",
+      webm: "video/webm",
+      pdf: "application/pdf",
+    }[ext] || "application/octet-stream"
+  );
+}
+
+async function detectSiblingAssetsDir(filePath) {
+  const { existsSync, statSync } = await import("node:fs");
+  const { dirname, basename, extname, join } = await import("node:path");
+  const dir = dirname(filePath);
+  const stem = basename(filePath, extname(filePath));
+  const candidates = [
+    `${stem}_files`,
+    `${stem} files`,
+    `${basename(filePath)}_files`,
+  ];
+  for (const name of candidates) {
+    const p = join(dir, name);
+    if (existsSync(p) && statSync(p).isDirectory()) return p;
+  }
+  return null;
+}
+
+async function collectAssets(assetsRoot) {
+  const { readFileSync, readdirSync, statSync } = await import("node:fs");
+  const { join, relative, sep, basename } = await import("node:path");
+  const rootStat = statSync(assetsRoot);
+  if (!rootStat.isDirectory()) {
+    throw new Error(`assetsDir must point to a directory: ${assetsRoot}`);
+  }
+  const collected = [];
+  const walk = (dir) => {
+    for (const name of readdirSync(dir)) {
+      const absPath = join(dir, name);
+      const st = statSync(absPath);
+      if (st.isDirectory()) {
+        walk(absPath);
+      } else if (st.isFile()) {
+        const relPath = relative(assetsRoot, absPath).split(sep).join("/");
+        collected.push({ absPath, relPath, bytes: st.size });
+      }
+    }
+  };
+  walk(assetsRoot);
+  if (collected.length === 0) {
+    throw new Error(`assetsDir is empty: ${assetsRoot}`);
+  }
+  const rootName = basename(assetsRoot);
+  const looksLikeSavePageDir = /[_ ]files$/i.test(rootName);
+  const finalPaths = looksLikeSavePageDir
+    ? collected.map((c) => ({ ...c, relPath: `${rootName}/${c.relPath}` }))
+    : collected;
+  let totalBytes = 0;
+  for (const item of finalPaths) {
+    if (item.relPath.split("/").some((seg) => seg === "..")) {
+      throw new Error(`asset path "${item.relPath}" contains "..", refused`);
+    }
+    if (item.bytes > MAX_ASSET_BYTES) {
+      throw new Error(
+        `asset "${item.relPath}" is ${item.bytes} bytes; cap is ${MAX_ASSET_BYTES}`,
+      );
+    }
+    totalBytes += item.bytes;
+    if (totalBytes > MAX_BUNDLE_BYTES) {
+      throw new Error(`total asset bytes exceeds ${MAX_BUNDLE_BYTES}`);
+    }
+  }
+  return {
+    assets: finalPaths.map((item) => ({
+      ...item,
+      data: readFileSync(item.absPath),
+      contentType: mimeForAsset(item.relPath),
+    })),
+    totalBytes,
+  };
+}
+
+async function uploadHtmlFromFile({
+  dealId,
+  filePath,
+  documentSlug,
+  source = "agent",
+  assetsDir,
+  autoDetectAssets = true,
+  verify = true,
+  clientUploadId,
+}) {
+  const { readFileSync, statSync } = await import("node:fs");
+  const st = statSync(filePath);
+  if (!st.isFile()) throw new Error(`filePath must point to a file: ${filePath}`);
+  const html = readFileSync(filePath, "utf8");
+  if (!html.trim()) throw new Error("HTML body is empty.");
+  const htmlBytes = Buffer.byteLength(html, "utf8");
+  if (htmlBytes > MAX_HTML_BYTES) {
+    throw new Error(
+      `HTML body is ${(htmlBytes / 1024 / 1024).toFixed(2)} MB; cap is 5 MB.`,
+    );
+  }
+  if (!looksLikeHtml(html)) {
+    throw new Error("HTML must start with <!doctype html> or <html.");
+  }
+
+  let effectiveAssetsDir = assetsDir || null;
+  if (!effectiveAssetsDir && autoDetectAssets !== false) {
+    effectiveAssetsDir = await detectSiblingAssetsDir(filePath);
+  }
+  const uploadId = normalizeUploadId(clientUploadId) || newHtmlUploadId();
+
+  let body;
+  if (!effectiveAssetsDir) {
+    body = await request("PUT", htmlUrl(dealId, documentSlug), {
+      html,
+      source,
+      client_upload_id: uploadId,
+    }, {
+      headers: { "X-Llama-Upload-Id": uploadId },
+    });
+  } else {
+    const { assets, totalBytes } = await collectAssets(effectiveAssetsDir);
+    const form = new FormData();
+    form.append("html", html);
+    form.append("source", source);
+    form.append("client_upload_id", uploadId);
+    for (const asset of assets) {
+      form.append(
+        `asset:${asset.relPath}`,
+        new Blob([asset.data], { type: asset.contentType }),
+        asset.relPath,
+      );
+    }
+    const headers = await getAuthHeaders();
+    const res = await fetch(`${getBaseUrl()}${htmlUrl(dealId, documentSlug)}`, {
+      method: "PUT",
+      headers: { ...headers, "X-Llama-Upload-Id": uploadId },
+      body: form,
+    });
+    body = await res.json().catch(() => ({}));
+    if (!res.ok) {
+      throw new Error(
+        `HTTP ${res.status}: ${body?.error || JSON.stringify(body).slice(0, 300)}`,
+      );
+    }
+    body = { ...body, asset_bytes: body.asset_bytes ?? totalBytes };
+  }
+
+  let verified = { ok: false, skipped: true };
+  if (verify !== false) {
+    const latest = await request("GET", htmlUrl(dealId, documentSlug));
+    if (latest?.empty) throw new Error("verification failed: document came back empty after upload");
+    if (body?.version != null && Number(latest.version) !== Number(body.version)) {
+      throw new Error(`verification failed: expected version ${body.version}, got ${latest.version}`);
+    }
+    if (body?.bytes != null && latest.bytes != null && Number(latest.bytes) !== Number(body.bytes)) {
+      throw new Error(`verification failed: expected ${body.bytes} bytes, got ${latest.bytes}`);
+    }
+    if (body?.sha256 && latest.sha256 && String(latest.sha256) !== String(body.sha256)) {
+      throw new Error(`verification failed: expected sha256 ${body.sha256}, got ${latest.sha256}`);
+    }
+    verified = {
+      ok: true,
+      version: latest.version,
+      bytes: latest.bytes,
+      sha256: latest.sha256,
+      created_at: latest.created_at,
+    };
+  }
+
+  return {
+    ok: true,
+    document_slug: documentSlug || "main",
+    version: body?.version,
+    bytes: body?.bytes ?? verified.bytes ?? htmlBytes,
+    sha256: body?.sha256 ?? verified.sha256,
+    client_upload_id: body?.client_upload_id ?? uploadId,
+    idempotent_replay: body?.idempotent_replay,
+    asset_count: body?.asset_count,
+    asset_bytes: body?.asset_bytes,
+    assets_dir: effectiveAssetsDir,
+    verified,
+    viewer: `${getBaseUrl()}/deals/${encodeURIComponent(dealId)}/browse/${encodeURIComponent(documentSlug || "main")}`,
+  };
+}
+
 server.registerTool(
   "html_show",
   {
     description:
       "Read the current hand-authored HTML 'deal page' for a deal. " +
       "Returns {empty: true} if no one has uploaded HTML yet, or " +
-      "{empty: false, version, html, bytes, uploaded_by, source, " +
+      "{empty: false, version, html, bytes, sha256, uploaded_by, source, " +
       "created_at}. The HTML can be 5-500KB — be deliberate about " +
       "including the body in your reply. Use html_versions if you " +
       "just want the version list without the body. Each deal can " +
@@ -1424,7 +1656,9 @@ server.registerTool(
       "Creates a NEW version row — the previous version is retained " +
       "and restorable. Triggers SSE push so any open viewer auto- " +
       "refreshes. Constraints: HTML body MUST start with " +
-      "<!doctype html> or <html (case-insensitive); max 5 MB. ALWAYS " +
+      "<!doctype html> or <html (case-insensitive); max 5 MB. Reliability guard: " +
+      "this inline-string tool refuses bodies over 50KB; use html_upload_file " +
+      "or `llama html publish --file` for memos/reports. ALWAYS " +
       "call html_show first if anything exists — replace only the " +
       "relevant section, don't lose unrelated content. Source defaults " +
       "to 'agent' for MCP-originated uploads. Pass documentSlug to " +
@@ -1440,13 +1674,76 @@ server.registerTool(
         .enum(["web", "cli", "agent"])
         .optional()
         .describe("default: agent"),
+      clientUploadId: z.string().optional().describe("optional retry id; reuse the same value if retrying the same small inline upload"),
     },
   },
-  async ({ dealId, html, documentSlug, source }) =>
-    callApi("PUT", htmlUrl(dealId, documentSlug), {
+  async ({ dealId, html, documentSlug, source, clientUploadId }) => {
+    const bytes = Buffer.byteLength(String(html || ""), "utf8");
+    if (bytes > INLINE_HTML_UPLOAD_LIMIT) {
+      return textResult(
+        `Error: html_upload received ${(bytes / 1024).toFixed(1)} KB of inline HTML. ` +
+          `For reliability, do not pass large HTML through MCP tool arguments. ` +
+          `Use html_upload_file({ dealId, filePath, documentSlug }) or run ` +
+          `\`llama html publish <deal-id-or-name> --file <path> --doc <slug>\` instead.`,
+        true,
+      );
+    }
+    let uploadId;
+    try {
+      uploadId = normalizeUploadId(clientUploadId) || newHtmlUploadId();
+    } catch (err) {
+      return textResult(`Error: ${err?.message ?? String(err)}`, true);
+    }
+    return callApi("PUT", htmlUrl(dealId, documentSlug), {
       html,
       source: source ?? "agent",
-    })
+      client_upload_id: uploadId,
+    }, {
+      headers: { "X-Llama-Upload-Id": uploadId },
+    });
+  }
+);
+
+server.registerTool(
+  "html_upload_file",
+  {
+    description:
+      "Agent-safe HTML upload from a LOCAL FILE PATH. Use this instead " +
+      "of html_upload for any substantial memo/report; it avoids moving " +
+      "large HTML through the model/tool-call context. Reads filePath on " +
+      "the machine running this MCP server, preflights size/HTML shape, " +
+      "optionally auto-detects a sibling *_files asset folder, uploads, " +
+      "then reads the document back to verify version/bytes/sha256. For a higher " +
+      "level CLI flow that can resolve deal names and choose create/update, " +
+      "run `llama html publish <deal-id-or-name> --file <path>`.",
+    inputSchema: {
+      dealId: z.string().describe("deal uuid"),
+      filePath: z.string().describe("absolute or relative local filesystem path to the HTML file"),
+      documentSlug: z.string().optional().describe("default: 'main'"),
+      source: z.enum(["web", "cli", "agent"]).optional().describe("default: agent"),
+      assetsDir: z.string().optional().describe("optional local directory of relative assets"),
+      autoDetectAssets: z.boolean().optional().describe("default true; detects sibling *_files folders"),
+      verify: z.boolean().optional().describe("default true; read-after-write verification"),
+      clientUploadId: z.string().optional().describe("optional retry id; reuse the same value if retrying the same failed upload"),
+    },
+  },
+  async ({ dealId, filePath, documentSlug, source, assetsDir, autoDetectAssets, verify, clientUploadId }) => {
+    try {
+      const result = await uploadHtmlFromFile({
+        dealId,
+        filePath,
+        documentSlug,
+        source: source ?? "agent",
+        assetsDir,
+        autoDetectAssets,
+        verify,
+        clientUploadId,
+      });
+      return jsonResult(result);
+    } catch (err) {
+      return textResult(`Error: ${err?.message ?? String(err)}`, true);
+    }
+  },
 );
 
 server.registerTool(
@@ -1454,7 +1751,7 @@ server.registerTool(
   {
     description:
       "List version history for a deal's /browse page HTML. Returns " +
-      "an array of {version, bytes, uploaded_by, source, created_at, " +
+      "an array of {version, bytes, sha256, uploaded_by, source, created_at, " +
       "deleted_at} — newest first, including soft-deleted versions. " +
       "Use to find a target version for html_restore.",
     inputSchema: {
@@ -1547,11 +1844,12 @@ server.registerTool(
   "html_upload_bundle",
   {
     description:
-      "Upload HTML + binary assets as one atomic version. Use this " +
-      "INSTEAD of html_upload when the HTML references local images / " +
-      "fonts / CSS files via relative src=/href= attributes (typical " +
-      "of 'Save Page As Complete' exports). The server stores HTML + " +
-      "each asset as one transactional bundle (deal_browse_assets " +
+      "Legacy small inline upload for HTML + binary assets as one atomic version. " +
+      "For substantial memos/reports or 'Save Page As Complete' exports, use " +
+      "html_upload_file with filePath + assetsDir instead so large HTML/assets " +
+      "do not move through the model/tool-call context. This inline bundle " +
+      "tool refuses payloads over 50KB. The server stores HTML + each asset as " +
+      "one transactional bundle (deal_browse_assets " +
       "table), rewrites the HTML refs to version-pinned URLs at " +
       "/api/deals/<id>/asset/<path>?v=N, and triggers SSE push. " +
       "Constraints: HTML <= 5 MB; each asset <= 50 MB; total bundle " +
@@ -1587,12 +1885,32 @@ server.registerTool(
         .enum(["web", "cli", "agent"])
         .optional()
         .describe("default: agent"),
+      clientUploadId: z.string().optional().describe("optional retry id; reuse the same value if retrying the same bundle upload"),
     },
   },
-  async ({ dealId, html, assets, documentSlug, source }) => {
+  async ({ dealId, html, assets, documentSlug, source, clientUploadId }) => {
+    const inlineBytes =
+      Buffer.byteLength(String(html || ""), "utf8") +
+      assets.reduce((sum, a) => sum + Buffer.byteLength(String(a.base64 || ""), "utf8"), 0);
+    if (inlineBytes > INLINE_HTML_UPLOAD_LIMIT) {
+      return textResult(
+        `Error: html_upload_bundle received ${(inlineBytes / 1024).toFixed(1)} KB of inline tool-call payload. ` +
+          `For reliability, do not pass large HTML/assets through MCP arguments. ` +
+          `Use html_upload_file({ dealId, filePath, documentSlug, assetsDir }) or run ` +
+          `\`llama html publish <deal-id-or-name> --file <path> --assets <dir>\` instead.`,
+        true,
+      );
+    }
+    let uploadId;
+    try {
+      uploadId = normalizeUploadId(clientUploadId) || newHtmlUploadId();
+    } catch (err) {
+      return textResult(`Error: ${err?.message ?? String(err)}`, true);
+    }
     const form = new FormData();
     form.append("html", html);
     form.append("source", source ?? "agent");
+    form.append("client_upload_id", uploadId);
     for (const a of assets) {
       const bytes = Buffer.from(a.base64, "base64");
       form.append(
@@ -1604,7 +1922,7 @@ server.registerTool(
     const headers = await getAuthHeaders();
     const res = await fetch(`${getBaseUrl()}${htmlUrl(dealId, documentSlug)}`, {
       method: "PUT",
-      headers, // let fetch set multipart Content-Type with boundary
+      headers: { ...headers, "X-Llama-Upload-Id": uploadId }, // let fetch set multipart Content-Type with boundary
       body: form,
     });
     const body = await res.json().catch(() => ({}));