amalgm 0.1.99 → 0.1.100

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amalgm",
-  "version": "0.1.99",
+  "version": "0.1.100",
   "description": "Amalgm local computer runtime: login, MCP, chat, events, previews, and tunnels.",
   "license": "UNLICENSED",
   "private": false,

package/runtime/scripts/amalgm-mcp/lib/email-embeds.js

@@ -0,0 +1,343 @@
+/**
+ * Email embed widgets — the email-safe mirror of the UI's shared rendering
+ * primitives: FileEmbed (media), EmbedChrome (the floating name/options
+ * pills on expanded embeds), and the tile:/full: entity renders.
+ *
+ * Email clients strip <style>, position:absolute, and most interactivity,
+ * so the chrome pills sit in a header row inside the same rounded-16
+ * stone-900 card instead of floating over the media — visually the same
+ * language, structurally email-safe. Gmail/Outlook drop <video> but render
+ * its fallback content; Apple Mail and iOS Mail play video inline.
+ *
+ * Media table mirrors amalgm-ui/lib/rendering/media.ts; visual values
+ * mirror EMAIL_TOKENS in email-md.js / lib/rendering/tokens.ts. Keep all
+ * three in sync.
+ */
+
+const COLOR = {
+  text: '#ffffff',
+  textMuted: '#a8a29e', // stone-400
+  border: '#1c1917', // stone-900 — container borders
+  pillBorder: '#292524', // stone-800
+  bg: '#000000',
+  bgChip: '#0c0a09', // stone-950
+  link: '#60a5fa', // blue-400
+};
+
+const EXTENSION_MIME = {
+  // Images
+  png: 'image/png',
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  gif: 'image/gif',
+  webp: 'image/webp',
+  svg: 'image/svg+xml',
+  avif: 'image/avif',
+  bmp: 'image/bmp',
+  ico: 'image/x-icon',
+  // Video
+  webm: 'video/webm',
+  mp4: 'video/mp4',
+  m4v: 'video/mp4',
+  mov: 'video/quicktime',
+  mkv: 'video/x-matroska',
+  ogv: 'video/ogg',
+  // Audio
+  mp3: 'audio/mpeg',
+  wav: 'audio/wav',
+  m4a: 'audio/mp4',
+  ogg: 'audio/ogg',
+  flac: 'audio/flac',
+  // Documents
+  pdf: 'application/pdf',
+  docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+  xls: 'application/vnd.ms-excel',
+  csv: 'text/csv',
+  tsv: 'text/tab-separated-values',
+};
+
+function escapeAttr(value) {
+  return String(value)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+function escapeText(value) {
+  return String(value).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+
+function mediaExtensionOf(nameOrUrl) {
+  const withoutQuery = String(nameOrUrl || '').split(/[?#]/)[0];
+  const base = withoutQuery.split('/').pop() || '';
+  const dot = base.lastIndexOf('.');
+  return dot > 0 ? base.slice(dot + 1).toLowerCase() : '';
+}
+
+function mediaMimeOf(nameOrUrl) {
+  return EXTENSION_MIME[mediaExtensionOf(nameOrUrl)] || null;
+}
+
+function mediaKindOf(nameOrUrl) {
+  const mime = mediaMimeOf(nameOrUrl);
+  if (!mime) return 'unknown';
+  if (mime.startsWith('image/')) return 'image';
+  if (mime.startsWith('video/')) return 'video';
+  if (mime.startsWith('audio/')) return 'audio';
+  return 'document';
+}
+
+function mediaNameOf(nameOrUrl) {
+  const withoutQuery = String(nameOrUrl || '').split(/[?#]/)[0];
+  const base = withoutQuery.split('/').pop() || '';
+  try {
+    return decodeURIComponent(base);
+  } catch {
+    return base;
+  }
+}
+
+function isHttpUrl(url) {
+  return /^https?:\/\//i.test(url);
+}
+
+/** Inline attachment reference — the image bytes ride inside the email. */
+function isCidUrl(url) {
+  return /^cid:/i.test(url);
+}
+
+/** Self-contained image source: fetchable over https or embedded as cid. */
+function isEmbeddableImageSrc(url) {
+  return isHttpUrl(url) || isCidUrl(url);
+}
+
+// --- EmbedChrome (email form) ------------------------------------------------
+
+function chromePill(content) {
+  return `<span style="display:inline-block;background:${COLOR.bgChip};border:1px solid ${COLOR.pillBorder};border-radius:999px;padding:4px 12px;font-size:12px;line-height:16px;color:${COLOR.text};white-space:nowrap">${content}</span>`;
+}
+
+/**
+ * The expanded-embed card: rounded-16 stone-900 border, black fill, a header
+ * row carrying the name pill (left) and an action pill (right), media below.
+ * actionLabel+actionHref make the right pill a link; actionText makes it a
+ * plain label (e.g. "Attachment").
+ */
+function embedShell({ name, actionLabel, actionHref, actionText, body }) {
+  const namePill = name ? chromePill(escapeText(name)) : '';
+  const actionPill = actionLabel && actionHref
+    ? `<a href="${escapeAttr(actionHref)}" target="_blank" style="text-decoration:none">${chromePill(
+        `<span style="color:${COLOR.link}">${escapeText(actionLabel)}</span>`,
+      )}</a>`
+    : actionText
+      ? chromePill(`<span style="color:${COLOR.textMuted}">${escapeText(actionText)}</span>`)
+      : '';
+  return (
+    `<div style="border:1px solid ${COLOR.border};border-radius:16px;background:${COLOR.bg};margin:16px 0;overflow:hidden">` +
+    `<table role="presentation" width="100%" cellpadding="0" cellspacing="0"><tr>` +
+    `<td align="left" style="padding:10px 10px 8px">${namePill}</td>` +
+    `<td align="right" style="padding:10px 10px 8px">${actionPill}</td>` +
+    `</tr></table>` +
+    body +
+    `</div>`
+  );
+}
+
+// --- Media embeds -------------------------------------------------------------
+
+/** Bare rounded image per the ruleset — images never wear chrome. */
+function renderImageEmbed(alt, url) {
+  return `<img src="${escapeAttr(url)}" alt="${escapeAttr(alt || '')}" style="display:block;max-width:100%;height:auto;border-radius:16px;border:1px solid ${COLOR.border};margin:16px 0">`;
+}
+
+const PLAY_PILL =
+  `<span style="display:inline-block;background:${COLOR.bgChip};border:1px solid ${COLOR.pillBorder};border-radius:999px;padding:10px 20px;font-size:14px;color:${COLOR.text}">&#9654;&nbsp;&nbsp;Play video</span>`;
+
+/** Poster frame + centered play pill, optionally wrapped in a link. */
+function posterBlock(posterSrc, label, href) {
+  const img = `<img src="${escapeAttr(posterSrc)}" alt="${escapeAttr(label || 'video')}" style="display:block;width:100%;height:auto;background:${COLOR.bg}">`;
+  const pillRow =
+    `<table role="presentation" width="100%" cellpadding="0" cellspacing="0"><tr>` +
+    `<td align="center" style="padding:12px 16px 16px;background:${COLOR.bg}">${PLAY_PILL}</td></tr></table>`;
+  const inner = img + pillRow;
+  return href
+    ? `<a href="${escapeAttr(href)}" target="_blank" style="text-decoration:none;display:block">${inner}</a>`
+    : inner;
+}
+
+/**
+ * Video embed: a real <video> for clients that support it (Apple Mail, iOS
+ * Mail), with a fallback that Gmail/Outlook render instead — the poster
+ * frame when one is provided, a play card otherwise.
+ */
+function renderVideoEmbed(label, url, poster) {
+  const name = label || mediaNameOf(url) || 'Video';
+  const safeUrl = escapeAttr(url);
+  const posterSrc = poster && isEmbeddableImageSrc(poster) ? poster : null;
+  const fallback = posterSrc
+    ? posterBlock(posterSrc, name, url)
+    : `<table role="presentation" width="100%" cellpadding="0" cellspacing="0"><tr>` +
+      `<td align="center" style="padding:48px 16px;background:${COLOR.bg}">` +
+      `<a href="${safeUrl}" target="_blank" style="text-decoration:none">${PLAY_PILL}</a></td></tr></table>`;
+  const body =
+    `<video controls preload="metadata" src="${safeUrl}"${posterSrc ? ` poster="${escapeAttr(posterSrc)}"` : ''} style="display:block;width:100%;max-height:480px;background:${COLOR.bg}">` +
+    fallback +
+    `</video>`;
+  return embedShell({ name, actionLabel: 'Open ↗', actionHref: url, body });
+}
+
+/**
+ * A video that travels WITH the email as a regular attachment (the
+ * self-contained path for local recordings): poster frame in the body when
+ * available, and the file itself in the mail client's attachment strip —
+ * Gmail gives attached videos a playable preview natively.
+ */
+function renderAttachedVideoCard(label, poster) {
+  const name = label || 'Video';
+  const posterSrc = poster && isEmbeddableImageSrc(poster) ? poster : null;
+  const note =
+    `<table role="presentation" width="100%" cellpadding="0" cellspacing="0"><tr>` +
+    `<td align="center" style="padding:${posterSrc ? '0 16px 16px' : '40px 16px 16px'};background:${COLOR.bg}">` +
+    (posterSrc ? '' : `${PLAY_PILL}<br>`) +
+    `<span style="display:inline-block;padding-top:8px;font-size:12px;color:${COLOR.textMuted}">Attached to this email &mdash; open the attachment to play</span>` +
+    `</td></tr></table>`;
+  const body = (posterSrc
+    ? `<img src="${escapeAttr(posterSrc)}" alt="${escapeAttr(name)}" style="display:block;width:100%;height:auto;background:${COLOR.bg}">`
+    : '') + note;
+  return embedShell({ name, actionText: 'Attachment', body });
+}
+
+/**
+ * Non-playable file in an embed position (pdf/docx/audio/anything): the
+ * compact file row from FileEmbed, as a card linking out.
+ */
+function renderFileCardEmbed(label, url) {
+  const name = label || mediaNameOf(url) || 'File';
+  const ext = mediaExtensionOf(name).toUpperCase();
+  const inner =
+    `<span style="font-size:13px;color:${COLOR.text}">${escapeText(name)}</span>` +
+    (ext ? `<span style="font-size:10px;color:${COLOR.textMuted};padding-left:8px">${escapeText(ext)}</span>` : '');
+  const body = isHttpUrl(url)
+    ? `<a href="${escapeAttr(url)}" target="_blank" style="text-decoration:none;display:block;padding:4px 14px 14px">${inner}<span style="font-size:12px;color:${COLOR.link};padding-left:10px">Open &#8599;</span></a>`
+    : `<div style="padding:4px 14px 14px">${inner}<span style="font-size:12px;color:${COLOR.textMuted};padding-left:10px">On your computer &mdash; open in amalgm</span></div>`;
+  return embedShell({
+    name,
+    actionLabel: isHttpUrl(url) ? 'Open ↗' : 'amalgm ↗',
+    actionHref: isHttpUrl(url) ? url : 'https://amalgm.ai',
+    body,
+  });
+}
+
+/**
+ * Media dispatch for `![label](url "poster")` in an email.
+ *
+ * Self-contained sources produced by the notify media pipeline:
+ *   cid:<id>          — image bytes ride inside the email (inline attachment)
+ *   attached:<name>   — video travels as a regular attachment; the body
+ *                       shows its poster card
+ * The optional markdown title carries the video poster (cid: or https).
+ * Local sources that could not be attached (amalgm:// refs or filesystem
+ * paths) fall back to the file card.
+ */
+function renderMediaEmbed(alt, url, poster) {
+  if (isCidUrl(url)) {
+    return renderImageEmbed(alt, url);
+  }
+  const attachedMatch = url.match(/^attached:(.*)$/i);
+  if (attachedMatch) {
+    let name = attachedMatch[1];
+    try {
+      name = decodeURIComponent(name);
+    } catch {}
+    return renderAttachedVideoCard(alt || name, poster);
+  }
+  const amalgmMatch = url.match(/^amalgm:\/\/file\/([^\s)?"]+)/);
+  if (amalgmMatch) {
+    let decoded = amalgmMatch[1];
+    try {
+      decoded = decodeURIComponent(decoded);
+    } catch {}
+    return renderFileCardEmbed(alt || mediaNameOf(decoded), decoded);
+  }
+  if (!isHttpUrl(url)) {
+    return renderFileCardEmbed(alt || mediaNameOf(url), url);
+  }
+  const kind = mediaKindOf(url);
+  if (kind === 'video') return renderVideoEmbed(alt, url, poster);
+  if (kind === 'audio' || kind === 'document') return renderFileCardEmbed(alt, url);
+  // Images and extension-less URLs keep vanilla image semantics.
+  return renderImageEmbed(alt, url);
+}
+
+// --- Entity embeds (tile: / full:) ---------------------------------------------
+
+const ENTITY_TYPE_LABEL = {
+  chat: 'Chat',
+  conversation: 'Chat',
+  automation: 'Automation',
+  app: 'App',
+  artifact: 'App',
+  service: 'App',
+  preview: 'Preview',
+  task: 'Task',
+  event: 'Event',
+  trigger: 'Trigger',
+};
+
+function entityTypeLabel(type) {
+  return ENTITY_TYPE_LABEL[type] || (type ? type.charAt(0).toUpperCase() + type.slice(1) : 'Item');
+}
+
+/**
+ * Inline tile — the email form of the chat's render tile: a compact linked
+ * card with a type eyebrow and the entity name, pointing at the amalgm app.
+ */
+function renderEntityTile(label, type) {
+  const safeLabel = escapeText(label || entityTypeLabel(type));
+  return (
+    `<a href="https://amalgm.ai" target="_blank" style="text-decoration:none;display:inline-block;background:${COLOR.bgChip};border:1px solid ${COLOR.pillBorder};border-radius:12px;padding:8px 14px;margin:2px 0;vertical-align:middle">` +
+    `<span style="display:block;font-size:11px;line-height:14px;color:${COLOR.textMuted};text-transform:uppercase;letter-spacing:0.04em">${escapeText(entityTypeLabel(type))}</span>` +
+    `<span style="display:block;font-size:14px;line-height:20px;color:${COLOR.text}">${safeLabel}</span>` +
+    `</a>`
+  );
+}
+
+/**
+ * Expanded entity — the email form of the full: render. Email can't iframe
+ * the live app, so it's the EmbedChrome card with the entity identity and a
+ * prominent open action.
+ */
+function renderEntityExpanded(label, type) {
+  const display = label || entityTypeLabel(type);
+  const body =
+    `<table role="presentation" width="100%" cellpadding="0" cellspacing="0"><tr>` +
+    `<td align="center" style="padding:36px 16px 40px">` +
+    `<span style="display:block;font-size:11px;line-height:14px;color:${COLOR.textMuted};text-transform:uppercase;letter-spacing:0.04em;padding-bottom:6px">${escapeText(entityTypeLabel(type))}</span>` +
+    `<span style="display:block;font-size:16px;font-weight:650;color:${COLOR.text};padding-bottom:16px">${escapeText(display)}</span>` +
+    `<a href="https://amalgm.ai" target="_blank" style="text-decoration:none">` +
+    `<span style="display:inline-block;background:${COLOR.bgChip};border:1px solid ${COLOR.pillBorder};border-radius:999px;padding:8px 18px;font-size:13px;color:${COLOR.link}">Open in amalgm &#8599;</span>` +
+    `</a></td></tr></table>`;
+  return embedShell({ name: display, actionLabel: 'Open ↗', actionHref: 'https://amalgm.ai', body });
+}
+
+function renderEntityEmbed(mode, type, label) {
+  return mode === 'full' ? renderEntityExpanded(label, type) : renderEntityTile(label, type);
+}
+
+module.exports = {
+  mediaExtensionOf,
+  mediaMimeOf,
+  mediaKindOf,
+  mediaNameOf,
+  isHttpUrl,
+  isCidUrl,
+  isEmbeddableImageSrc,
+  renderImageEmbed,
+  renderVideoEmbed,
+  renderAttachedVideoCard,
+  renderFileCardEmbed,
+  renderMediaEmbed,
+  renderEntityEmbed,
+};

package/runtime/scripts/amalgm-mcp/lib/email-md.js

@@ -11,8 +11,14 @@
  * rendering ruleset in amalgm-ui/lib/rendering/tokens.ts — keep both in sync:
  * body 14px, h1 caps at 18px (the amalgm section-header size), Notion-style
  * table grid, black chat-style code blocks, blue hyperlinks/citations.
+ *
+ * Media (`![label](url)`) and entity renders (`[label](tile:type:id)`,
+ * `[label](full:type:id)`) on their own line become block embeds via
+ * lib/email-embeds.js — the email mirror of FileEmbed/EmbedChrome/tiles.
  */
 
+const embeds = require('./email-embeds');
+
 const EMAIL_TOKENS = {
   font: {
     text: "'SF Pro Text',-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,'Helvetica Neue',sans-serif",
@@ -69,10 +75,28 @@ function renderAmalgmCitation(label, _kindAndPath, description) {
 function inlineFormat(text) {
   return (
     text
-      // Images: ![alt](url)
+      // Media mid-sentence: images stay inline; video becomes a play link;
+      // local files become a citation-blue span. (Standalone media lines are
+      // handled as block embeds in markdownToEmailHtml before reaching here.)
       .replace(
-        /!\[([^\]]*)\]\(([^)]+)\)/g,
-        '<img src="$2" alt="$1" style="max-width:100%;height:auto;border-radius:16px;margin:8px 0">',
+        /!\[([^\]]*)\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g,
+        (_, alt, url) => {
+          if (/^attached:/i.test(url)) {
+            return `<span style="color:${EMAIL_TOKENS.color.link}">${escapeHtmlText(alt || 'video')}</span> <span style="color:${EMAIL_TOKENS.color.textSecondary}">(attached)</span>`;
+          }
+          if (!embeds.isEmbeddableImageSrc(url)) {
+            return `<span style="color:${EMAIL_TOKENS.color.link}">${escapeHtmlText(alt || embeds.mediaNameOf(url) || 'file')}</span>`;
+          }
+          if (embeds.mediaKindOf(url) === 'video') {
+            return `<a href="${escapeHtmlAttr(url)}" target="_blank" style="color:${EMAIL_TOKENS.color.link};text-decoration:none">&#9654;&nbsp;${escapeHtmlText(alt || 'video')}</a>`;
+          }
+          return `<img src="${escapeHtmlAttr(url)}" alt="${escapeHtmlAttr(alt)}" style="max-width:100%;height:auto;border-radius:16px;margin:8px 0">`;
+        },
+      )
+      // Entity renders mid-sentence collapse to the compact tile.
+      .replace(
+        /\[([^\]]+)\]\((tile|full):([a-zA-Z]+):([^)\s]*)\)/g,
+        (_, label, mode, type) => embeds.renderEntityEmbed('tile', type, label),
       )
       // amalgm:// citations (run before generic link regex so the optional
       // title attribute doesn't get swallowed into the href). Format:
@@ -230,6 +254,22 @@ function markdownToEmailHtml(md) {
       out.push(`<hr style="border:none;border-top:1px solid ${EMAIL_TOKENS.color.border};margin:24px 0">`);
       continue;
     }
+    // Standalone media line → block embed (image bare, video in the
+    // EmbedChrome card, attached/local/doc files as cards). The optional
+    // title carries a video poster: ![label](url "cid:poster-1").
+    const mediaMatch = trimmed.match(/^!\[([^\]]*)\]\(([^)\s]+)(?:\s+"([^"]*)")?\)$/);
+    if (mediaMatch) {
+      flushAll();
+      out.push(embeds.renderMediaEmbed(mediaMatch[1], mediaMatch[2], mediaMatch[3] || null));
+      continue;
+    }
+    // Standalone entity render → tile card or expanded card.
+    const entityMatch = trimmed.match(/^\[([^\]]+)\]\((tile|full):([a-zA-Z]+):([^)\s]*)\)$/);
+    if (entityMatch) {
+      flushAll();
+      out.push(embeds.renderEntityEmbed(entityMatch[2], entityMatch[3], entityMatch[1]));
+      continue;
+    }
     const headingMatch = trimmed.match(/^(#{1,6})\s+(.+)$/);
     if (headingMatch) {
       flushAll();

package/runtime/scripts/amalgm-mcp/notify/email-media.js

@@ -0,0 +1,169 @@
+/**
+ * Self-contained email media pipeline.
+ *
+ * notify_user messages may embed media that lives on this computer
+ * (`![label](amalgm://file/...)` or absolute paths). A mail client can never
+ * fetch those, so before rendering we convert them into attachments that
+ * travel WITH the email:
+ *
+ *  - images → inline CID attachments; the src is rewritten to `cid:<id>` so
+ *    the picture displays in the body, fully offline.
+ *  - videos → regular attachments (Gmail gives those a playable preview);
+ *    the src is rewritten to `attached:<filename>` which email-embeds
+ *    renders as the poster card. The poster comes from an explicit markdown
+ *    title (`![clip](path "poster-path")`), then a sibling animated
+ *    `<name>.preview.gif` / `<name>.gif`, then a static
+ *    `<name>.poster.png` / `.jpg` / `.jpeg` / `.webp`, and itself becomes an
+ *    inline CID.
+ *
+ * Anything that can't be attached (missing file, too large, over budget) is
+ * left untouched so the renderer falls back to its file card. Web https
+ * sources are never rewritten.
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { mediaKindOf, mediaMimeOf } = require('../lib/email-embeds');
+
+const MAX_IMAGE_BYTES = 8 * 1024 * 1024;
+const MAX_VIDEO_BYTES = 20 * 1024 * 1024;
+const MAX_TOTAL_BYTES = 22 * 1024 * 1024; // proxy caps at 25MB; leave margin
+const MAX_ATTACHMENTS = 8;
+
+const MEDIA_LINE_RE = /^!\[([^\]]*)\]\(([^)\s]+)(?:\s+"([^"]*)")?\)$/;
+
+/** Resolve a media src to an absolute path on this computer, or null. */
+function resolveLocalPath(src) {
+  if (!src) return null;
+  const amalgmMatch = src.match(/^amalgm:\/\/file\/([^?#]+)/);
+  if (amalgmMatch) {
+    try {
+      return decodeURIComponent(amalgmMatch[1]);
+    } catch {
+      return amalgmMatch[1];
+    }
+  }
+  if (src.startsWith('file://')) return decodeURIComponentSafe(src.slice('file://'.length));
+  let candidate = src;
+  try {
+    candidate = decodeURIComponent(src);
+  } catch {}
+  if (candidate.startsWith('~/')) return path.join(os.homedir(), candidate.slice(2));
+  if (candidate.startsWith('/')) return candidate;
+  return null;
+}
+
+function decodeURIComponentSafe(value) {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}
+
+function statSafe(filePath) {
+  try {
+    const stat = fs.statSync(filePath);
+    return stat.isFile() ? stat : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Sibling preview for a video, best first:
+ *  - <name>.preview.gif / <name>.gif — animated GIF; Gmail animates inline
+ *    CID GIFs, so the email "plays" the clip right in the body
+ *  - <name>.poster.png/jpg/jpeg/webp — static first frame
+ * (<name> is the full filename or its stem.)
+ */
+function findSiblingPoster(videoPath) {
+  const dir = path.dirname(videoPath);
+  const base = path.basename(videoPath);
+  const stem = base.replace(/\.[^.]+$/, '');
+  const candidates = [];
+  for (const name of [base, stem]) {
+    candidates.push(path.join(dir, `${name}.preview.gif`), path.join(dir, `${name}.gif`));
+  }
+  for (const name of [base, stem]) {
+    for (const ext of ['png', 'jpg', 'jpeg', 'webp']) {
+      candidates.push(path.join(dir, `${name}.poster.${ext}`));
+    }
+  }
+  return candidates.find((candidate) => statSafe(candidate)) || null;
+}
+
+/**
+ * Convert local media embeds in a markdown message into email attachments.
+ * Returns { message, attachments } — message has cid:/attached: sources,
+ * attachments are in the proxy's shape (filename, content, contentType,
+ * contentId?).
+ */
+function prepareEmailMedia(message) {
+  const attachments = [];
+  let totalBytes = 0;
+  let counter = 0;
+
+  const budgetAllows = (bytes) =>
+    attachments.length < MAX_ATTACHMENTS && totalBytes + bytes <= MAX_TOTAL_BYTES;
+
+  const attachFile = (filePath, stat, contentId) => {
+    const content = fs.readFileSync(filePath).toString('base64');
+    totalBytes += stat.size;
+    attachments.push({
+      filename: path.basename(filePath),
+      content,
+      contentType: mediaMimeOf(filePath) || 'application/octet-stream',
+      ...(contentId ? { contentId } : {}),
+    });
+  };
+
+  const attachPoster = (posterSource) => {
+    // Poster may be an explicit local source or an https URL (kept as-is).
+    if (!posterSource) return null;
+    if (/^https?:\/\//i.test(posterSource) || /^cid:/i.test(posterSource)) return posterSource;
+    const posterPath = resolveLocalPath(posterSource);
+    const stat = posterPath ? statSafe(posterPath) : null;
+    if (!stat || stat.size > MAX_IMAGE_BYTES || !budgetAllows(stat.size)) return null;
+    if (mediaKindOf(posterPath) !== 'image') return null;
+    const contentId = `poster-${++counter}`;
+    attachFile(posterPath, stat, contentId);
+    return `cid:${contentId}`;
+  };
+
+  const lines = message.split('\n').map((line) => {
+    const match = line.trim().match(MEDIA_LINE_RE);
+    if (!match) return line;
+    const [, alt, src, title] = match;
+
+    if (/^(https?:|cid:|attached:|data:)/i.test(src)) return line;
+    const filePath = resolveLocalPath(src);
+    const stat = filePath ? statSafe(filePath) : null;
+    if (!stat) return line;
+
+    const kind = mediaKindOf(filePath);
+
+    if (kind === 'image') {
+      if (stat.size > MAX_IMAGE_BYTES || !budgetAllows(stat.size)) return line;
+      const contentId = `media-${++counter}`;
+      attachFile(filePath, stat, contentId);
+      return `![${alt || path.basename(filePath)}](cid:${contentId})`;
+    }
+
+    if (kind === 'video') {
+      if (stat.size > MAX_VIDEO_BYTES || !budgetAllows(stat.size)) return line;
+      attachFile(filePath, stat, null);
+      const poster = attachPoster(title) || attachPoster(findSiblingPoster(filePath));
+      const label = alt || path.basename(filePath);
+      const target = `attached:${encodeURIComponent(path.basename(filePath))}`;
+      return poster ? `![${label}](${target} "${poster}")` : `![${label}](${target})`;
+    }
+
+    return line;
+  });
+
+  return { message: lines.join('\n'), attachments };
+}
+
+module.exports = { prepareEmailMedia };

package/runtime/scripts/amalgm-mcp/notify/index.js

@@ -9,6 +9,7 @@
 const { PROXY_BASE_URL, PROXY_TOKEN } = require('../config');
 const { ensureFreshProxyToken, readProxyToken } = require('../../proxy-token-store');
 const { formatNotificationEmail } = require('../lib/email-md');
+const { prepareEmailMedia } = require('./email-media');
 const { textResult, errorResult } = require('../lib/tool-result');
 
 async function notifyUserViaProxy({ subject: customSubject, message, link, sessionId }) {
@@ -27,7 +28,10 @@ async function notifyUserViaProxy({ subject: customSubject, message, link, sessi
 
   const subject =
     (customSubject && customSubject.trim()) || message.slice(0, 80).replace(/\n/g, ' ');
-  const html = formatNotificationEmail(message, link || null);
+  // Local media embeds become attachments riding inside the email: images
+  // inline via cid:, videos as regular attachments with a poster card.
+  const media = prepareEmailMedia(message);
+  const html = formatNotificationEmail(media.message, link || null);
 
   try {
     const res = await fetch(notifyUrl, {
@@ -40,6 +44,7 @@ async function notifyUserViaProxy({ subject: customSubject, message, link, sessi
         subject,
         html,
         text: message,
+        ...(media.attachments.length ? { attachments: media.attachments } : {}),
         ...(sessionId ? { sessionId } : {}),
       }),
     });
@@ -64,7 +69,7 @@ module.exports = [
   {
     name: 'notify_user',
     description:
-      'Send a notification to the user via email (from emails@amalgm.ai). Use this to keep the user informed about important results, completions, or errors — especially during scheduled tasks, event triggers, and long-running operations where the user is likely not actively watching.\n\nBest practices:\n- Always call notify_user at the end of a scheduled task or event-triggered run.\n- For errors, include enough context that the user can act without opening the session.\n- Keep it scannable: lead with what happened, then details.\n\nFormatting: The message is rendered as full markdown. You can use headings (##), **bold**, *italic*, `inline code`, ```code blocks```, [links](url), lists (- or 1.), blockquotes (>), and --- horizontal rules. Write it like a concise status update — no greeting, no sign-off, just the information.',
+      'Send a notification to the user via email (from emails@amalgm.ai). Use this to keep the user informed about important results, completions, or errors — especially during scheduled tasks, event triggers, and long-running operations where the user is likely not actively watching.\n\nBest practices:\n- Always call notify_user at the end of a scheduled task or event-triggered run.\n- For errors, include enough context that the user can act without opening the session.\n- Keep it scannable: lead with what happened, then details.\n\nFormatting: The message is rendered as full markdown. You can use headings (##), **bold**, *italic*, `inline code`, ```code blocks```, [links](url), tables, lists (- or 1.), blockquotes (>), and --- horizontal rules. Rich embeds on their own line: `![label](amalgm://file/ENCODED_PATH)` with a local image attaches it INSIDE the email and displays it inline; with a local video (webm/mp4/mov, ≤20MB) the file travels as a real attachment and the body shows a poster card. Poster preference: explicit markdown title `![clip](path "poster-path")`, then sibling `<name>.preview.gif` / `<name>.gif` for Gmail-friendly motion, then static `<name>.poster.png` / `.jpg` / `.jpeg` / `.webp`. `![label](https://...)` embeds web media (video player with play-card fallback). `[label](tile:TYPE:ID)` / `[label](full:TYPE:ID)` render entity cards linking back to amalgm. Write it like a concise status update — no greeting, no sign-off, just the information.',
     inputSchema: {
       type: 'object',
       properties: {

package/runtime/scripts/amalgm-mcp/tests/core-tools.test.js

@@ -44,6 +44,16 @@ test('core tool actions carry stable toolbox ids', () => {
   assert.equal(notifyUser.toolboxActionId, 'notifications.notify_user');
 });
 
+test('notify_user description teaches self-contained video embeds with GIF previews', () => {
+  const notifyUser = CORE_TOOLS.find((tool) => tool.name === 'notify_user');
+
+  assert.equal(notifyUser.description.includes('![label](amalgm://file/ENCODED_PATH)'), true);
+  assert.equal(notifyUser.description.includes('<name>.preview.gif'), true);
+  assert.equal(notifyUser.description.includes('<name>.gif'), true);
+  assert.equal(notifyUser.description.includes('<name>.poster.png'), true);
+  assert.equal(notifyUser.description.includes('≤20MB'), true);
+});
+
 test('browser is a single toolbox entry holding every browser action', () => {
   const browser = CORE_TOOL_GROUPS.find((group) => group.id === 'browser');
   assert.deepEqual(browser.tools.map((tool) => tool.name), [

package/runtime/scripts/amalgm-mcp/tests/email-media.test.js

@@ -0,0 +1,34 @@
+'use strict';
+
+const assert = require('node:assert/strict');
+const test = require('node:test');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const { prepareEmailMedia } = require('../notify/email-media');
+
+test('prepareEmailMedia attaches local video and prefers sibling animated GIF preview', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'amalgm-email-media-'));
+  try {
+    const videoPath = path.join(dir, 'qa-pass.webm');
+    const gifPath = path.join(dir, 'qa-pass.preview.gif');
+    const staticPosterPath = path.join(dir, 'qa-pass.poster.png');
+    fs.writeFileSync(videoPath, Buffer.from('not really a webm but enough for extension detection'));
+    fs.writeFileSync(gifPath, Buffer.from('GIF89a'));
+    fs.writeFileSync(staticPosterPath, Buffer.from('png fallback should not be chosen'));
+
+    const src = `amalgm://file/${encodeURIComponent(videoPath)}`;
+    const result = prepareEmailMedia(`Here is the recording:\n![QA recording](${src})`);
+
+    assert.match(result.message, /!\[QA recording\]\(attached:qa-pass\.webm "cid:poster-1"\)/);
+    assert.equal(result.attachments.length, 2);
+    assert.equal(result.attachments[0].filename, 'qa-pass.webm');
+    assert.equal(result.attachments[0].contentType, 'video/webm');
+    assert.equal(result.attachments[1].filename, 'qa-pass.preview.gif');
+    assert.equal(result.attachments[1].contentType, 'image/gif');
+    assert.equal(result.attachments[1].contentId, 'poster-1');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});

package/runtime/scripts/amalgm-mcp/tests/platform-context.test.js

@@ -44,3 +44,15 @@ test('platform context browser names match the registered actions', () => {
     assert.equal(text.includes(`\`${name}\``), true, `prompt should mention ${name}`);
   }
 });
+
+test('platform context teaches rich media embeds with GIF video previews', () => {
+  const text = fs.readFileSync(CONTEXT_PATH, 'utf8');
+
+  assert.equal(text.includes('## Embedding Images and Videos'), true);
+  assert.equal(text.includes('![label](src)'), true);
+  assert.equal(text.includes('amalgm://file/ENCODED_ABSOLUTE_PATH'), true);
+  assert.equal(text.includes('<name>.preview.gif'), true);
+  assert.equal(text.includes('<name>.gif'), true);
+  assert.equal(text.includes('<name>.poster.png'), true);
+  assert.equal(text.includes('≤20MB'), true);
+});

package/runtime/scripts/platform-context.txt

@@ -203,6 +203,19 @@ Types:
 - App: [label](full:app:APP_ID)
 - Preview: [label](full:preview:PORT)
 
+## Embedding Images and Videos
+
+Markdown image syntax is the embed syntax: `![label](src)` on its own line renders the media inline — in chat messages AND in notify_user emails. Use it to show screenshots, demo clips, and QA recordings instead of describing them.
+
+Sources:
+- Local file: `![run-recording.webm](amalgm://file/ENCODED_ABSOLUTE_PATH)` — percent-encode the path exactly like a file citation. Videos (webm/mp4/mov) get an inline player with name + options chrome; images render bare and rounded. PDFs, spreadsheets, and docx embed as document previews the same way.
+- Web URL: `![label](https://...)` — the extension decides the embed (video player for .webm/.mp4/.mov, image otherwise).
+
+Rules:
+- Put embeds on their own line. Mid-sentence, prefer a normal `amalgm://` file citation instead.
+- Emails are self-contained: a local image embed is attached inside the email and displays inline; a local video (≤20MB) travels as a real attachment with a poster card in the body. Poster preference: explicit markdown title `![clip](path "poster-path")`, then sibling `<name>.preview.gif` / `<name>.gif` for Gmail-friendly motion, then static `<name>.poster.png` / `.jpg` / `.jpeg` / `.webp`. Oversized or missing files degrade to a file card. Entity references (`tile:`/`full:`) work in email too, as cards.
+- Don't wrap embeds in backticks. A browser recording you just captured is a great thing to embed in your reply or in a QA report email.
+
 ## Citing Files, Folders, Skills, and Agents
 
 When you reference a file, folder, skill, or agent that exists on the user's local volume, emit it as an `amalgm://` markdown link. The frontend renders these as inline citation chips by default, with a hover card showing the path and (for skills) description. Skills are files too: if you only have the `SKILL.md` path, a normal file citation is valid. This is the same format the user's `@`-menu produces, and it's how agents talk to each other about local resources.