@comty.io/core 0.1.5 → 0.1.7

package/src/browser.js

@@ -1,3 +1,4 @@
+import { createInspectMarkup } from "./inspect-markup.js";
 import { getComtyStyle } from "./style.js";
 import { createAnchorMatcher } from "./anchors.js";
 import { createScreenshotCapture, createColorMagnifier, captureContext } from "./capture.js";
@@ -9,7 +10,17 @@ const instanceKey = Symbol.for("comty.sdk.instance");
 /** Initialize once per document; safe to import and call during server rendering. */
 export function initComty(options = {}) {
   if (typeof window === "undefined" || typeof document === "undefined") return Promise.resolve();
-  const projectKey = options.projectKey;
+  const isLocalSite = ["localhost", "127.0.0.1", "[::1]"].includes(window.location.hostname);
+  const agent = options.agent;
+  if (agent && (!isLocalSite || typeof agent.token !== "string" || !/^[a-f0-9]{64}$/.test(agent.token))) {
+    return Promise.reject(new TypeError("Comty: invalid local companion configuration"));
+  }
+  if (agent) {
+    try {
+      if (new URL(agent.url).origin !== window.location.origin) throw new Error();
+    } catch { return Promise.reject(new TypeError("Comty: companion must share the page origin")); }
+  }
+  const projectKey = options.projectKey || (agent ? "local" : undefined);
   const apiUrl = options.apiUrl || "http://localhost:4000";
   if (typeof projectKey !== "string" || !projectKey.trim()) {
     return Promise.reject(new TypeError("Comty: projectKey is required"));
@@ -21,12 +32,14 @@ export function initComty(options = {}) {
   if (!["http:", "https:"].includes(parsedApi.protocol)) {
     return Promise.reject(new TypeError("Comty: apiUrl must be an absolute HTTP(S) URL"));
   }
-  const configuration = JSON.stringify([projectKey, apiUrl]);
+  const configuration = JSON.stringify([projectKey, apiUrl, agent || null]);
   const existing = window[instanceKey];
   if (existing) {
     return existing.configuration === configuration ? existing.ready
       : Promise.reject(new Error("Comty: already initialized with different options"));
   }
+  const agentBridgeUrl = agent?.url;
+  const localOnly = Boolean(agent && !options.projectKey);
   const ready = new Promise((resolve, reject) => {
     const mount = () => {
       try { resolve(mountComty()); } catch (error) { reject(error); }
@@ -40,10 +53,24 @@ export function initComty(options = {}) {
 
   function mountComty() {
     let projectId = null;
+    let localTasks = [];
+    const deliveringAgentReplies = new Set();
+    let localApprovals = [];
+    const seenAgentApprovals = new Set();
+    // Only requests made in this document may interrupt it with agent notifications.
+    const requestedAgentTasks = new Set();
+    let agentPanelOpen = false;
+    let agentPanelSignature = "";
+    let agentPanelTransition = 0;
+    let agentConnectionError = "";
+    let agentActionError = "";
+    let clearAgentToast = () => {};
+    const agentPendingActions = new Set();
     const session = {
       mode: "off",
-      get comments() { return this.mode === "browse" || this.mode === "edit"; },
-      get edit() { return this.mode === "edit"; },
+      get comments() { return this.mode === "browse" || this.mode === "edit" || this.mode === "agent"; },
+      get edit() { return this.mode === "edit" || this.mode === "agent"; },
+      get agent() { return this.mode === "agent"; },
       get inspect() { return this.mode === "inspect"; },
     };
     const selectedStatusFilters = new Set();
@@ -67,9 +94,10 @@ export function initComty(options = {}) {
     const authReturnStorageKey = `comty:${projectKey}:auth-return`;
     let sdkToken = "";
     const activeHoverCommentIds = new Set();
-    /** @type {null | 'edit' | 'browse'} */
+    /** @type {null | 'edit' | 'browse' | 'agent'} */
     let sessionEntry = null;
     const placedPins = new Map();
+    const workingOutlines = new Map();
     const placementDiagnostics = new Map();
     let inspectedElement = null;
     let selectedElement = null;
@@ -83,8 +111,8 @@ export function initComty(options = {}) {
     const commentTargets = new Map();
 
     const {
-      matchesAnchorContext, resolveByAnchorContext,
-      isElementTreeHidden, getTopActiveModal, getVisibleAnchorPoint,
+      matchesAnchorContext,
+      resolveAnchor, isElementTreeHidden, getTopActiveModal, getVisibleAnchorPoint,
     } = createAnchorMatcher({
       getElementTextSignature,
       getElementOwnTextSignature,
@@ -162,10 +190,27 @@ export function initComty(options = {}) {
     const inspectorBtn = toolButton("Inspect · Shift I", '<path d="M8 3H5a2 2 0 0 0-2 2v3m13-5h3a2 2 0 0 1 2 2v3M3 16v3a2 2 0 0 0 2 2h3m13-5v3a2 2 0 0 1-2 2h-3"/><path d="m9 9 8 4-4 1-1 4Z"/>', () => setSession("inspect"));
     const btn = toolButton("Comment · Shift C", '<path d="M21 11.5a8.4 8.4 0 0 1-.9 3.8 8.5 8.5 0 0 1-7.6 4.7 8.4 8.4 0 0 1-3.8-.9L3 21l1.9-5.7a8.4 8.4 0 0 1-.9-3.8 8.5 8.5 0 0 1 4.7-7.6A8.4 8.4 0 0 1 12.5 3h.5a8.5 8.5 0 0 1 8 8v.5Z"/>', () => {
       if (!canWrite) showAuthPrompt();
-      else if (session.inspect || !isSessionActive()) startEditSession();
+      else if (session.agent || session.inspect || !isSessionActive()) startEditSession();
       else if (!session.edit) setSession("edit", { entry: sessionEntry });
     });
     btn.id = "comty-toggle";
+    const agentBtn = isLocalSite
+      ? toolButton("Agent task · localhost only", '<path d="M8 7 3 12l5 5m8-10 5 5-5 5M14 4l-4 16"/>', () => {
+          if (session.agent) {
+            const failedTask = [...localTasks].reverse().find(task => task.status === 'in_review' && !task.thread_comment_id);
+            const failedPin = failedTask && placedPins.get(String(failedTask.id));
+            if (failedPin && !failedPin.hasAttribute('data-comty-anchor-hidden')) { failedPin.click(); return; }
+            if (localTasks.some(task => task.status === 'in_review' || (!task.thread_comment_id && task.status === 'done')) || localApprovals.length) {
+              agentPanelOpen = true;
+              renderAgentPanel();
+            }
+          } else startAgentSession();
+        })
+      : null;
+    if (agentBtn) {
+      agentBtn.title = "Agent · Shift A · localhost only";
+      agentBtn.setAttribute("aria-keyshortcuts", "Shift+A");
+    }
     const divider = document.createElement("span");
     divider.className = "comty-tool-divider";
     toolbar.appendChild(divider);
@@ -175,7 +220,7 @@ export function initComty(options = {}) {
     const primaryTools = document.createElement("div");
     primaryTools.className = "comty-tool-primary";
     toolbar.insertBefore(primaryTools, browseBtn);
-    for (const button of [browseBtn, inspectorBtn, btn]) primaryTools.appendChild(button);
+    for (const button of [browseBtn, inspectorBtn, btn, agentBtn].filter(Boolean)) primaryTools.appendChild(button);
     const inspectorTools = document.createElement("div");
     inspectorTools.className = "comty-tool-context";
     inspectorTools.hidden = true;
@@ -205,6 +250,7 @@ export function initComty(options = {}) {
       root,
       isComtyElement,
       isElementTreeHidden,
+      isInteractionBlocked: () => Boolean(markup.mode),
       onExit() { rulersEnabled = false; syncInspectorTools(); },
     });
     const gridLayer = document.createElement("div");
@@ -231,6 +277,7 @@ export function initComty(options = {}) {
       syncInspectorTools();
     });
     const rulersBtn = toolButton("Rulers · R", '<path d="M3 3h18v6H9v12H3Z"/><path d="M7 3v3m4-3v3m4-3v3M3 11h3m-3 4h3m-3 4h3"/>', () => {
+      markup.setMode(null);
       closePropertyPanel();
       if (motion.enabled) setMotionEnabled(false);
       rulersEnabled = !rulersEnabled;
@@ -241,6 +288,7 @@ export function initComty(options = {}) {
       syncInspectorTools();
     });
     const gridBtn = toolButton("Layout guides · G", '<rect x="3" y="3" width="18" height="18" rx="2"/><path d="M3 10h18M10 3v18"/>', () => {
+      markup.setMode(null);
       closePropertyPanel();
       if (motion.enabled) setMotionEnabled(false);
       gridPanelOpen = !gridPanelOpen;
@@ -258,7 +306,37 @@ export function initComty(options = {}) {
     }
     const motionBtn = toolButton("Motion · M", '<circle cx="12" cy="14" r="8"/><path d="M9 2h6m-3 4V2m6 5 2-2m-8 5v4l3 2"/>', () => setMotionEnabled(!motion.enabled));
     motionBtn.setAttribute("aria-expanded", "false");
-    for (const button of [xrayBtn, rulersBtn, gridBtn, pipetteBtn, typographyBtn, motionBtn]) inspectorTools.appendChild(button);
+    const annotateBtn = toolButton("Annotate · D", '<path d="m16 3 5 5L8 21H3v-5ZM14 5l5 5"/>', () => toggleMarkup("annotate"));
+    const screenshotBtn = toolButton("Capture area · S", '<path d="M8 3H5a2 2 0 0 0-2 2v3m13-5h3a2 2 0 0 1 2 2v3M3 16v3a2 2 0 0 0 2 2h3m13-5v3a2 2 0 0 1-2 2h-3"/><rect x="7" y="8" width="10" height="8" rx="1"/><circle cx="12" cy="12" r="2"/>', () => toggleMarkup("capture"));
+    const markup = createInspectMarkup({
+      root, icon,
+      onError: description => showNotice({ title: "Screenshot unavailable", description }),
+      onChange() {
+        annotateBtn.setAttribute("aria-pressed", String(markup.mode === "annotate"));
+        annotateBtn.setAttribute("aria-expanded", String(markup.mode === "annotate"));
+        screenshotBtn.setAttribute("aria-pressed", String(markup.mode === "capture"));
+        screenshotBtn.setAttribute("aria-busy", String(markup.busy));
+        positionToolbar();
+      },
+      capture: (region, layer) => captureViewportScreenshot({ region, annotation: () => ({
+        elements: [overlayTools, root.querySelector('.comty-distance-layer'), layer].filter(node => node && !node.hidden),
+        dispose() {},
+      }) }),
+    });
+    for (const button of [annotateBtn]) {
+      button.setAttribute("aria-controls", markup.panel.id);
+      button.setAttribute("aria-expanded", "false");
+    }
+    function toggleMarkup(mode) {
+      const next = markup.mode === mode ? null : mode;
+      closePropertyPanel();
+      if (motion.enabled) setMotionEnabled(false);
+      gridPanelOpen = false; toolPanel.hidden = true; gridBtn.setAttribute("aria-expanded", "false");
+      cancelRulerDrag();
+      selectedElement = null; measuredRegion = null; inspectDrag = null; hideInspector();
+      markup.setMode(next);
+    }
+    for (const button of [xrayBtn, rulersBtn, gridBtn, pipetteBtn, typographyBtn, motionBtn, annotateBtn, screenshotBtn]) inspectorTools.appendChild(button);
 
     const motion = { enabled: false, speed: 1, paused: false, managed: new Map(), shadowRoots: [], nextRootScan: 0 };
     const motionPanel = document.createElement('section');
@@ -307,6 +385,7 @@ export function initComty(options = {}) {
       motion.enabled = enabled; motionPanel.hidden = !enabled;
       motionBtn.setAttribute('aria-pressed', String(enabled)); motionBtn.setAttribute('aria-expanded', String(enabled));
       if (enabled) {
+        markup.setMode(null);
         closePropertyPanel();
         rulersEnabled = false;
         syncInspectorTools();
@@ -565,6 +644,7 @@ export function initComty(options = {}) {
       const visible = session.inspect;
       measurements.setEnabled(visible && rulersEnabled && !motion.enabled);
       overlayTools.hidden = !visible;
+      markup.setVisible(visible);
       xrayBtn.setAttribute("aria-pressed", String(visible && xrayEnabled));
       rulersBtn.setAttribute("aria-pressed", String(visible && rulersEnabled));
       gridBtn.setAttribute("aria-pressed", String(visible && layoutGuides.some(guide => guide.visible)));
@@ -848,6 +928,7 @@ export function initComty(options = {}) {
     }
 
     function openPropertyPanel(kind, element, property, opener = null, sampledColor = null) {
+      markup.setMode(null);
       propertyPicking = null;
       colorMagnifier.setEnabled(false);
       delete document.documentElement.dataset.comtyPropertyPicking;
@@ -1028,6 +1109,50 @@ export function initComty(options = {}) {
     let toolbarMotionFrame = 0;
     let toolbarAnimations = [];
     const reducedMotion = matchMedia("(prefers-reduced-motion: reduce)");
+    let workingIndicatorTimer = 0;
+    function scheduleWorkingIndicators() {
+      if (workingIndicatorTimer || reducedMotion.matches || document.hidden) return;
+      workingIndicatorTimer = setTimeout(() => {
+        workingIndicatorTimer = 0;
+        if (!root.isConnected) return;
+        const indicators = root.querySelectorAll('.comty-working-indicator');
+        if (!indicators.length) return;
+        for (const indicator of indicators) {
+          const previous = Number(indicator.dataset.activeDots.split(',')[0]);
+          const first = (previous + 1 + Math.floor(Math.random() * 8)) % 9;
+          const second = (first + 1 + Math.floor(Math.random() * 8)) % 9;
+          indicator.dataset.activeDots = `${first},${second}`;
+          [...indicator.children].forEach((dot, index) => dot.toggleAttribute('data-active', index === first || index === second));
+        }
+        scheduleWorkingIndicators();
+      }, 600);
+    }
+    function createWorkingIndicator() {
+      const indicator = document.createElement('span');
+      indicator.className = 'comty-working-indicator';
+      indicator.setAttribute('aria-hidden', 'true');
+      indicator.dataset.activeDots = '3,5';
+      for (let index = 0; index < 9; index++) {
+        const dot = document.createElement('i');
+        dot.toggleAttribute('data-active', index === 3 || index === 5);
+        indicator.appendChild(dot);
+      }
+      scheduleWorkingIndicators();
+      return indicator;
+    }
+    function resetWorkingIndicators() {
+      clearTimeout(workingIndicatorTimer);
+      workingIndicatorTimer = 0;
+      if (reducedMotion.matches) {
+        for (const indicator of root.querySelectorAll('.comty-working-indicator')) {
+          indicator.dataset.activeDots = '3,5';
+          [...indicator.children].forEach((dot, index) => dot.toggleAttribute('data-active', index === 3 || index === 5));
+        }
+      }
+      if (root.querySelector('.comty-working-indicator')) scheduleWorkingIndicators();
+    }
+    reducedMotion.addEventListener('change', resetWorkingIndicators);
+    document.addEventListener('visibilitychange', resetWorkingIndicators);
     const clampToolbar = (value, size, viewport) => Math.max(8, Math.min(value, viewport - size - 8));
     function rememberToolbarPosition(left, top) {
       const width = toolbar.offsetWidth, height = toolbar.offsetHeight;
@@ -1061,7 +1186,7 @@ export function initComty(options = {}) {
         });
       }
       const rect = toolbar.getBoundingClientRect();
-      for (const panel of [toolPanel, propertyPanel, sidepanel, motionPanel]) {
+      for (const panel of [toolPanel, propertyPanel, sidepanel, motionPanel, markup.panel]) {
         if (panel.hidden || (panel === sidepanel && !sidepanelOpen)) continue;
         const above = rect.top - 16;
         const below = innerHeight - rect.bottom - 16;
@@ -1078,9 +1203,10 @@ export function initComty(options = {}) {
         panel.style.top = `${useAbove ? rect.top - panel.offsetHeight - 8 : rect.bottom + 8}px`;
         panel.style.bottom = "auto";
       }
+      positionNotice();
     }
     const toolbarResize = new ResizeObserver(positionToolbar);
-    [toolbar, toolPanel, propertyPanel, sidepanel, motionPanel].forEach(node => toolbarResize.observe(node));
+    [toolbar, toolPanel, propertyPanel, sidepanel, motionPanel, markup.panel].forEach(node => toolbarResize.observe(node));
     window.addEventListener("resize", positionToolbar);
 
     toolbar.addEventListener("pointerdown", event => {
@@ -1140,7 +1266,7 @@ export function initComty(options = {}) {
 
     function prepareToolbarMotion() {
       if (toolbarMotionFrame) return;
-      const nodes = [toolbarSurface, dragHandle, primaryTools, commentTools, inspectorTools].filter(Boolean);
+      const nodes = [toolbarSurface, dragHandle, primaryTools, commentTools, inspectorTools];
       // Move each group's background with its icons, including when interrupted.
       const before = new Map(nodes.filter(node => !node.hidden).map(node => [node, {
         rect: node.getBoundingClientRect(), opacity: getComputedStyle(node).opacity,
@@ -1364,7 +1490,8 @@ export function initComty(options = {}) {
         selectedElement = null;
         sessionEntry = null;
         session.mode = "off";
-        document.documentElement.classList.remove("comty-comments-active", "comty-comment-placement");
+        syncPlacementCursor();
+        document.documentElement.classList.remove("comty-comments-active", "comty-inspect-annotations");
         hideInspector();
         setSidepanelOpen(false);
         closeBubbles();
@@ -1378,25 +1505,29 @@ export function initComty(options = {}) {
       if (mode === "off") return;
       if (mode === "inspect") {
         session.mode = "inspect";
+        document.documentElement.classList.add("comty-inspect-annotations");
         syncToolbar();
+        renderCachedComments();
         ensureLiveTracking();
         return;
       }
 
-      if (session.edit && mode === "browse") {
+      if ((session.edit && mode === "browse") || (session.agent && mode === "edit")) {
         closeBubbles();
       }
       const hadComments = session.comments;
       session.mode = mode;
       sessionEntry = entry;
+      document.documentElement.classList.remove("comty-inspect-annotations");
       document.documentElement.classList.toggle("comty-comments-active", session.comments);
-      document.documentElement.classList.toggle("comty-comment-placement", session.edit);
+      syncPlacementCursor();
       if (session.edit) {
         setMotionEnabled(false);
         selectedElement = null;
       } else {
         hideInspector();
       }
+      if (session.agent && sidepanelOpen) setSidepanelOpen(false);
       syncToolbar();
       ensureLiveTracking();
       if (renderComments || !hadComments) renderCachedComments();
@@ -1409,6 +1540,10 @@ export function initComty(options = {}) {
     }
 
     function showAuthPrompt(forbidden = false, onReady = startEditSession) {
+      if (localOnly) {
+        showNotice({ title: "Comments are not configured", description: "Connect this site to a Comty project to leave shared comments." });
+        return;
+      }
       const guestAllowed = allowGuestComments;
       document.querySelector(".comty-auth-backdrop")?.remove();
       const opener = document.activeElement;
@@ -1530,14 +1665,17 @@ export function initComty(options = {}) {
     }
 
     function syncToolbar() {
-      if (commentTools.hidden !== session.inspect || inspectorTools.hidden !== !session.inspect) prepareToolbarMotion();
+      if (commentTools.hidden !== (session.inspect || session.agent) || inspectorTools.hidden !== !session.inspect) prepareToolbarMotion();
       root.classList.toggle("comty-active", session.comments || session.edit || sidepanelOpen || session.inspect);
       browseBtn.setAttribute("aria-pressed", String(!session.edit && !session.inspect));
       inspectorBtn.setAttribute("aria-pressed", String(session.inspect));
-      btn.setAttribute("aria-pressed", String(session.edit));
-      commentTools.hidden = session.inspect;
+      btn.setAttribute("aria-pressed", String(session.edit && !session.agent));
+      agentBtn?.setAttribute("aria-pressed", String(session.edit && session.agent));
+      commentTools.hidden = session.inspect || session.agent;
       inspectorTools.hidden = !session.inspect;
       syncInspectorTools();
+      renderAgentPanel();
+      positionNotice();
     }
 
     const inspectionLayer = document.createElement("div");
@@ -1850,7 +1988,7 @@ export function initComty(options = {}) {
         });
         return;
       }
-      if (propertyPicking || motion.enabled || (session.inspect && rulersEnabled)) {
+      if (markup.mode || propertyPicking || motion.enabled || (session.inspect && rulersEnabled)) {
         if (inspectionLayer.childNodes.length) hideInspector();
         return;
       }
@@ -1994,10 +2132,20 @@ export function initComty(options = {}) {
 
     function startBrowseSession() {
       setSession("browse", { renderComments: true });
+      void loadComments({ force: true });
     }
 
     function startEditSession() {
       setSession("edit", { renderComments: true });
+      void loadComments({ force: true });
+    }
+
+    function startAgentSession() {
+      if (!isLocalSite) return;
+      if (session.agent) return;
+      closeBubbles();
+      setSession("agent", { renderComments: true });
+      void loadComments({ force: true });
     }
 
     function toggleSidepanel() {
@@ -2023,7 +2171,7 @@ export function initComty(options = {}) {
         showAuthPrompt();
         return;
       }
-      if (session.inspect || !isSessionActive()) {
+      if (session.agent || session.inspect || !isSessionActive()) {
         startEditSession();
         return;
       }
@@ -2311,6 +2459,24 @@ export function initComty(options = {}) {
         ancestors,
         layer: layer ? getElementFingerprint(layer) : null,
       };
+      // React exposes this in development builds. Keep it as a hint: the coding
+      // agent must confirm the component and variant in source before editing.
+      const fiberKey = Object.keys(el).find(key => key.startsWith('__reactFiber$'));
+      let fiber = fiberKey ? el[fiberKey] : null;
+      const components = [];
+      while (fiber && components.length < 8) {
+        const component = fiber.type;
+        const name = component?.displayName || component?.name;
+        if (name && typeof name === 'string') {
+          const props = fiber.memoizedProps || {};
+          const variants = Object.fromEntries(['variant', 'size', 'tone', 'appearance'].filter(key =>
+            ['string', 'number', 'boolean'].includes(typeof props[key])).map(key => [key, props[key]]));
+          const source = fiber._debugSource;
+          components.push({ name, variants, ...(source?.fileName ? { file: source.fileName, line: source.lineNumber } : {}) });
+        }
+        fiber = fiber.return;
+      }
+      if (components.length) context.components = components;
       context.candidateCount = [...document.querySelectorAll(context.target.tag)]
         .filter(candidate => !isComtyNode(candidate) && matchesAnchorContext(candidate, context)).length;
       return context;
@@ -2339,6 +2505,11 @@ export function initComty(options = {}) {
       };
     }
 
+    function getPagePath() {
+      const { pathname, hash } = window.location;
+      return pathname + (hash.startsWith("#/") || hash.startsWith("#!/") ? hash : "");
+    }
+
     function resolveBySelector(selector) {
       if (!selector) return null;
       try {
@@ -2360,17 +2531,9 @@ export function initComty(options = {}) {
       }
       const context = parseAnchorContext(comment);
       const exact = resolveBySelector(comment.selector || "body");
-      if (context?.candidateCount > 1) {
-        const count = [...document.querySelectorAll("*")].filter(candidate => candidate.tagName.toLowerCase() === context.target.tag)
-          .filter(candidate => !isComtyNode(candidate) && matchesAnchorContext(candidate, context)).length;
-        if (count !== context.candidateCount) {
-          commentTargets.set(key, { element: null, signature, revision: anchorRevision });
-          return null;
-        }
-      }
-      let element = exact && matchesAnchorContext(exact, context) ? getAnchorElement(exact) : null;
-      if (!element) element = resolveByAnchorContext(context);
-      commentTargets.set(key, { element, signature, revision: anchorRevision });
+      const resolution = resolveAnchor(context, exact);
+      const element = resolution.element ? getAnchorElement(resolution.element) : null;
+      commentTargets.set(key, { ...resolution, element, signature, revision: anchorRevision });
       return element;
     }
 
@@ -2441,9 +2604,14 @@ export function initComty(options = {}) {
       return { deviceType: "desktop", deviceLabel: "Desktop" };
     }
 
+    function syncPlacementCursor() {
+      document.documentElement.classList.toggle("comty-comment-placement", session.edit && !draftAnchor);
+    }
+
     function closeBubbles() {
       const hadDraft = Boolean(draftAnchor);
       draftAnchor = null;
+      syncPlacementCursor();
       activeHoverCommentIds.clear();
       if (!session.edit || hadDraft) hideInspector();
       document
@@ -2488,7 +2656,7 @@ export function initComty(options = {}) {
         pending: commentId.startsWith("pending-"),
         project_id: projectId,
         domain: payload.host || window.location.host,
-        page_path: payload.pagePath || window.location.pathname,
+        page_path: payload.pagePath || getPagePath(),
         selector: payload.selector || "body",
         rel_x: payload.relX,
         rel_y: payload.relY,
@@ -2513,7 +2681,7 @@ export function initComty(options = {}) {
         replies: [],
       };
 
-      cachedPagePath = window.location.pathname;
+      cachedPagePath = getPagePath();
       cachedComments = [
         ...cachedComments.filter(
           (cached) => getCommentId(cached) !== commentId,
@@ -2526,6 +2694,7 @@ export function initComty(options = {}) {
     }
 
     function getCommentAuthorName(comment) {
+      if (comment?.author_kind === 'agent') return 'Agent';
       return comment?.author_name || comment?.name || "Anonymous";
     }
 
@@ -2547,6 +2716,12 @@ export function initComty(options = {}) {
     function createCommentAvatar(comment, extraClass = "") {
       const avatar = document.createElement("span");
       avatar.className = `comty-comment-avatar${extraClass ? ` ${extraClass}` : ""}`;
+      if (comment?.author_kind === 'agent') {
+        avatar.classList.add('comty-agent-avatar');
+        avatar.setAttribute('aria-label', 'Agent');
+        avatar.innerHTML = '<svg viewBox="0 0 48 48" aria-hidden="true"><path d="M24 2C26.62 2 28.47 5.29 31.27 6.45C34.07 7.61 37.71 6.59 39.56 8.44C41.41 10.29 40.39 13.93 41.55 16.73C42.71 19.53 46 21.38 46 24C46 26.62 42.71 28.47 41.55 31.27C40.39 34.07 41.41 37.71 39.56 39.56C37.71 41.41 34.07 40.39 31.27 41.55C28.47 42.71 26.62 46 24 46C21.38 46 19.53 42.71 16.73 41.55C13.93 40.39 10.29 41.41 8.44 39.56C6.59 37.71 7.61 34.07 6.45 31.27C5.29 28.47 2 26.62 2 24C2 21.38 5.29 19.53 6.45 16.73C7.61 13.93 6.59 10.29 8.44 8.44C10.29 6.59 13.93 7.61 16.73 6.45C19.53 5.29 21.38 2 24 2Z" fill="currentColor"/><path fill="var(--comty-surface)" fill-rule="evenodd" d="M16 33 22.3 15h3.4L32 33h-3.3l-1.3-4h-6.8l-1.3 4H16Zm5.5-6.8h5L24 18.4l-2.5 7.8Z"/></svg>';
+        return avatar;
+      }
       const authorName = getCommentAuthorName(comment);
       const avatarUrl = getCommentAuthorAvatarUrl(comment);
 
@@ -2554,6 +2729,7 @@ export function initComty(options = {}) {
         const image = document.createElement("img");
         image.src = avatarUrl;
         image.alt = "";
+        image.draggable = false;
         image.onerror = () => {
           image.remove();
           avatar.innerText = authorName.charAt(0).toUpperCase();
@@ -2707,6 +2883,7 @@ export function initComty(options = {}) {
     function createCommentPin(comment, x, y) {
       const pin = document.createElement("button");
       pin.className = "comty-pin";
+      pin.toggleAttribute('data-agent-task', Boolean(comment.local_agent));
       pin.type = "button";
       pin.style.left = `${x}px`;
       pin.style.top = `${y}px`;
@@ -2724,10 +2901,52 @@ export function initComty(options = {}) {
       const thread = document.createElement("div");
       thread.className = "comty-thread";
       thread.appendChild(createThreadItem(comment, { showMore: false, showLink: false }).item);
+      if (comment.local_agent) {
+        thread.appendChild(createThreadItem({ author_kind: 'agent', content: 'Modification failed. Open to retry or dismiss.' }, { showMore: false }).item);
+      }
       bubble.appendChild(thread);
       return bubble;
     }
 
+    function openAgentTask(task, x, y) {
+      closeBubbles();
+      const bubble = document.createElement('div');
+      bubble.className = 'comty-bubble comty-agent-task-thread';
+      bubble.dataset.commentId = task.id;
+      bubble.setAttribute('role', 'dialog');
+      bubble.setAttribute('aria-label', 'Failed modification');
+      const header = document.createElement('div'); header.className = 'comty-bubble-header';
+      const title = document.createElement('strong'); title.textContent = 'Modification failed';
+      const close = document.createElement('button'); close.type = 'button'; close.className = 'comty-icon-button';
+      close.setAttribute('aria-label', 'Close failed modification');
+      close.innerHTML = icon('<path d="m6 6 12 12M6 18 18 6"/>');
+      close.onclick = () => closeBubbles();
+      header.append(title, close);
+      const thread = document.createElement('div'); thread.className = 'comty-thread';
+      const list = document.createElement('div'); list.className = 'comty-thread-list';
+      const issue = task.error ? describeAgentError(task.error) : null;
+      list.append(
+        createThreadItem(task, { showMore: false }).item,
+        createThreadItem({ author_kind: 'agent', content: task.result?.summary || issue?.message || issue?.description || 'The agent could not complete this request.' }, { showMore: false }).item,
+      );
+      thread.appendChild(list);
+      const actions = document.createElement('div'); actions.className = 'comty-agent-task-actions';
+      for (const action of ['retry', 'dismiss']) {
+        const button = document.createElement('button'); button.type = 'button'; button.className = 'comty-agent-action';
+        button.textContent = action === 'retry' ? 'Retry' : 'Dismiss';
+        button.onclick = async () => {
+          for (const control of actions.children) control.disabled = true;
+          try { await runAgentAction(`tasks/${task.id}/${action}`); }
+          catch (error) { showAgentBridgeError(error.message); }
+          finally { for (const control of actions.children) control.disabled = false; }
+        };
+        actions.appendChild(button);
+      }
+      bubble.append(header, thread, actions);
+      root.appendChild(bubble);
+      positionCommentBubble(bubble, x, y);
+    }
+
     function mountCaptureAnnotation(comment, { x, y }) {
       const host = document.createElement("div");
       host.dataset.comtyCaptureExclude = "";
@@ -2778,6 +2997,7 @@ export function initComty(options = {}) {
         payload,
         preview: { rect: target.getBoundingClientRect(), rows: getInspectRows(target), selector: getSelector(target), spacing: getSpacingPreview(target) },
       };
+      syncPlacementCursor();
       ensureLiveTracking();
 
       const pin = document.createElement("div");
@@ -2795,10 +3015,21 @@ export function initComty(options = {}) {
 
       const textarea = document.createElement("textarea");
       textarea.className = "comty-create-textarea";
-      textarea.placeholder = "Add a comment";
+      textarea.placeholder = payload.kind === "agent" ? "Ask a question or describe a change" : "Add a comment";
       textarea.setAttribute("aria-label", textarea.placeholder);
       textarea.rows = 1;
 
+      const scopePicker = document.createElement('label');
+      scopePicker.className = 'comty-agent-scope';
+      if (payload.kind === 'agent') {
+        const input = document.createElement('input');
+        input.type = 'checkbox';
+        input.setAttribute('aria-label', 'Apply to all instances of this variant');
+        const track = document.createElement('span'); track.className = 'comty-agent-scope-track'; track.setAttribute('aria-hidden', 'true');
+        scopePicker.title = 'Apply to all instances of this variant';
+        scopePicker.append(input, track, document.createTextNode('Apply globally'));
+      }
+
       const actions = document.createElement("div");
       actions.className = "comty-create-actions";
 
@@ -2852,7 +3083,7 @@ export function initComty(options = {}) {
       const submitBtn = document.createElement("button");
       submitBtn.type = "button";
       submitBtn.className = "comty-btn-submit";
-      submitBtn.setAttribute("aria-label", "Post comment");
+      submitBtn.setAttribute("aria-label", payload.kind === "agent" ? "Send agent task" : "Post comment");
       submitBtn.disabled = true;
       submitBtn.innerHTML = `
         <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
@@ -2869,49 +3100,63 @@ export function initComty(options = {}) {
         textarea.disabled = true;
         linkBtn.disabled = true;
 
+        if (payload.kind === "agent" && !agent) {
+          showAgentBridgeError(); submitBtn.disabled = false; textarea.disabled = false; return;
+        }
         payload.content = content;
+        if (payload.kind === 'agent') payload.scope = scopePicker.querySelector('input').checked ? 'variant' : 'element';
         payload.linkUrl = attachedLink || null;
         textarea.textContent = content;
 
-        const context = captureContext();
-        const point = getPinPoint(pin);
-        const pendingId = `pending-${crypto.randomUUID()}`;
-        // Paint the comment immediately. The network save never waits for capture work.
+        const isAgentTask = payload.kind === "agent";
+        const context = isAgentTask ? null : captureContext();
+        const point = isAgentTask ? null : getPinPoint(pin);
+        const pendingId = isAgentTask ? null : `pending-${crypto.randomUUID()}`;
         bubble.remove();
         pin.remove();
         if (draftAnchor === editorDraft) draftAnchor = null;
+        syncPlacementCursor();
         hideInspector();
-        addLocalComment(pendingId, payload);
+        if (!isAgentTask) addLocalComment(pendingId, payload);
         let post;
         try {
-          post = await fetch(`${apiUrl}/api/comments`, {
+          post = await fetch(payload.kind === "agent" ? `${agentBridgeUrl}/tasks` : `${apiUrl}/api/comments`, {
             method: "POST",
-            headers: getSdkHeaders({ "Content-Type": "application/json" }),
-            body: JSON.stringify(payload),
+            headers: payload.kind === "agent" ? agentHeaders() : getSdkHeaders({ "Content-Type": "application/json" }),
+            body: JSON.stringify(payload.kind === "agent" ? { ...payload, projectKey } : payload),
           });
-          if (!post.ok) throw new Error(`Comment save failed (${post.status})`);
+          if (!post.ok) throw new Error(`Save failed (${post.status})`);
           const data = await post.json();
-          if (!data?.id) throw new Error("Comment save returned no ID");
-          cachedComments = cachedComments.filter(item => String(item.id) !== pendingId);
-          if (context.url === location.href) {
-            const comment = addLocalComment(String(data.id), payload);
-            // Start only after the save and immediate UI update; the capture yields to input.
-            void uploadCommentScreenshot(comment, context, point);
-          } else void loadComments({ force: true });
+          const id = isAgentTask ? data?.task?.id : data?.id;
+          if (!id) throw new Error("Save returned no ID");
+          if (isAgentTask) {
+            requestedAgentTasks.add(id);
+            void loadComments({ force: true });
+          } else {
+            cachedComments = cachedComments.filter(item => String(item.id) !== pendingId);
+            if (context.url === location.href) {
+              const comment = addLocalComment(String(id), payload);
+              void uploadCommentScreenshot(comment, context, point);
+            } else void loadComments({ force: true });
+          }
         } catch (error) {
           console.error("Comty: save failed", error);
-          cachedComments = cachedComments.filter(item => String(item.id) !== pendingId);
-          renderSidepanelComments();
-          void renderComments(cachedComments, { retry: false });
+          if (isAgentTask) showAgentBridgeError(error.message);
+          else {
+            cachedComments = cachedComments.filter(item => String(item.id) !== pendingId);
+            renderSidepanelComments();
+            void renderComments(cachedComments, { retry: false });
+          }
           // Keep the original editor and its text available for retry, including attachments.
           if (!draftAnchor) draftAnchor = editorDraft;
+          syncPlacementCursor();
           root.append(pin, bubble);
           submitBtn.disabled = false;
           textarea.disabled = false;
           linkBtn.disabled = false;
           const errorMessage = document.createElement("p");
           errorMessage.setAttribute("role", "alert");
-          errorMessage.textContent = "Comment not saved. Your draft is ready to retry.";
+          errorMessage.textContent = `${isAgentTask ? "Task" : "Comment"} not saved. Your draft is ready to retry.`;
           bubble.querySelector('[role="alert"]')?.remove();
           bubble.append(errorMessage);
           if (bubble.isConnected) textarea.focus();
@@ -3000,7 +3245,8 @@ export function initComty(options = {}) {
         renderInspector();
       };
 
-      actions.append(linkBtn, submitBtn, linkEditor);
+      if (payload.kind === 'agent') actions.append(scopePicker, submitBtn);
+      else actions.append(linkBtn, submitBtn, linkEditor);
 
       bubble.appendChild(textarea);
       bubble.appendChild(attachment);
@@ -3013,6 +3259,249 @@ export function initComty(options = {}) {
       setTimeout(() => textarea.focus(), 10);
     }
 
+    function agentHeaders() { return { "Content-Type": "application/json", "X-Comty-Token": agent?.token || "" }; }
+
+    function showAgentBridgeError(message = "Start your app with comty dev to use the local agent. Check the terminal if it is already running.") {
+      const issue = describeAgentError(message);
+      showNotice({ title: 'Modification failed', description: issue.title === 'Task could not finish' ? 'The agent could not complete this request.' : issue.title + '.' });
+    }
+
+    function positionNotice() {
+      const toast = root.querySelector(".comty-agent-task-toast");
+      if (!toast) return;
+      toast.style.removeProperty("left");
+      toast.style.removeProperty("top");
+      toast.toggleAttribute("data-toolbar", isSessionActive());
+      if (!isSessionActive()) return;
+      const rect = toolbar.getBoundingClientRect();
+      const above = rect.top - toast.offsetHeight - 8;
+      toast.style.left = `${Math.max(8, Math.min(rect.right - toast.offsetWidth, innerWidth - toast.offsetWidth - 8))}px`;
+      toast.style.top = `${Math.max(8, Math.min(above >= 8 ? above : rect.bottom + 8, innerHeight - toast.offsetHeight - 8))}px`;
+    }
+
+    function showNotice(issue) {
+      clearAgentToast();
+      const toast = document.createElement("div");
+      toast.className = "comty-agent-task-toast";
+      toast.setAttribute("role", "alert");
+      const title = document.createElement("strong"); title.textContent = issue.title;
+      const description = document.createElement("p"); description.textContent = issue.description;
+      const close = document.createElement("button"); close.type = "button";
+      close.setAttribute("aria-label", "Dismiss notification");
+      close.innerHTML = icon('<path d="m6 6 12 12M6 18 18 6"/>');
+      toast.append(title, description, close);
+      let timer, leaving = false;
+      const dismiss = () => {
+        if (leaving) return;
+        leaving = true;
+        clearTimeout(timer);
+        toast.dataset.leaving = "";
+        timer = setTimeout(() => toast.remove(), reducedMotion.matches ? 0 : 200);
+      };
+      const schedule = () => { if (!leaving) { clearTimeout(timer); timer = setTimeout(dismiss, 6000); } };
+      const pause = () => { if (!leaving) clearTimeout(timer); };
+      clearAgentToast = () => { clearTimeout(timer); toast.remove(); };
+      close.onclick = dismiss;
+      toast.onmouseenter = pause;
+      toast.onmouseleave = schedule;
+      toast.onfocusin = pause;
+      toast.onfocusout = schedule;
+      root.appendChild(toast);
+      positionNotice();
+      schedule();
+    }
+
+    function describeAgentError(error) {
+      const raw = typeof error === 'string' ? error : JSON.stringify(error, null, 2) || 'Unknown error';
+      let value = error;
+      for (let depth = 0; depth < 8; depth++) {
+        if (typeof value === 'string') {
+          try { value = JSON.parse(value); continue; } catch {}
+          const start = value.indexOf('{'), end = value.lastIndexOf('}');
+          if (start >= 0 && end > start) { try { value = JSON.parse(value.slice(start, end + 1)); continue; } catch {} }
+          break;
+        }
+        if (!value || typeof value !== 'object') break;
+        value = value.error || value.message || value.cause || value.stderr || value;
+      }
+      const message = typeof value === 'string' ? value : '';
+      const source = raw + ' ' + message;
+      const agentName = /codex/i.test(source) ? 'Codex' : /claude/i.test(source) ? 'Claude Code' : /cursor/i.test(source) ? 'Cursor' : 'your coding agent';
+      let title, description;
+      if (/requires a newer version|upgrade.*latest|outdated|unsupported.*version/i.test(source)) {
+        title = 'Agent update required'; description = `Update ${agentName}, restart your local development session, then retry this task.`;
+      } else if (/insufficient_quota|quota exceeded|credit balance|billing|usage limit/i.test(source)) {
+        title = 'Usage limit reached'; description = 'Check your agent account’s usage allowance or billing, then retry when capacity is available.';
+      } else if (/rate.?limit|too many requests|\b429\b/i.test(source)) {
+        title = 'Too many requests'; description = 'The agent is temporarily rate limited. Wait a moment before retrying.';
+      } else if (/unauthorized|unauthenticated|authentication|not logged|sign.?in|log.?in|invalid.api.key|\b401\b/i.test(source)) {
+        title = 'Sign in to your agent'; description = `Open ${agentName} and sign in again, then retry this task.`;
+      } else if (/model.*(?:not found|does not exist|unavailable|not supported)|unsupported model|model_not_found/i.test(source)) {
+        title = 'Model unavailable'; description = 'The local agent rejected this model. Check its CLI version and signed-in account, then retry.';
+      } else if (/disconnected|ECONNREFUSED|ENOTFOUND|network|failed to fetch|development server stopped/i.test(source)) {
+        title = 'Connection lost'; description = 'Check that your local development server and coding agent are running, then reload this page.';
+      } else if (/timed? ?out|timeout|exceeded.*minutes/i.test(source)) {
+        title = 'Task timed out'; description = 'Review any changes already made, then retry with a smaller, more specific request.';
+      } else if (/permission|denied|forbidden|\b403\b/i.test(source)) {
+        title = 'Permission needed'; description = 'Check the agent’s access to this project and any pending approval before retrying.';
+      } else if (/ENOENT|command not found|not installed|executable.*not found/i.test(source)) {
+        title = 'Agent not found'; description = `Install or configure ${agentName} in your local development environment, then restart and retry.`;
+      } else if (/completion was not verified/i.test(source)) {
+        title = 'Result needs checking'; description = 'The agent could not confirm completion. Review the changes before retrying.';
+      } else {
+        title = 'Task could not finish';
+        description = message && !/[{}]|\[object Object\]/.test(message) ? message.slice(0, 160) + (message.length > 160 ? '…' : '') : 'The agent reported an unexpected error. Review the technical details and any changes before retrying.';
+      }
+      return { title, description, raw, message };
+    }
+
+    async function runAgentAction(path, input = {}) {
+      const response = await fetch(`${agentBridgeUrl}/${path}`, { method: 'POST', headers: agentHeaders(), body: JSON.stringify(input) });
+      if (!response.ok) {
+        const body = await response.json().catch(() => null);
+        throw new Error(typeof body?.error === 'string' ? body.error : JSON.stringify(body?.error || { status: response.status, message: 'Request failed' }));
+      }
+      if (path.endsWith('/retry')) requestedAgentTasks.add(path.split('/')[1]);
+      await loadComments({ force: true });
+    }
+
+    function renderAgentPanel() {
+      if (!agent) return;
+      const visibleTasks = [];
+      const latestResult = [...localTasks].reverse().find(task => ['done', 'in_review'].includes(task.status) && (!task.thread_comment_id || task.status === 'in_review'));
+      if (latestResult) visibleTasks.push(latestResult);
+      if (!visibleTasks.length && !localApprovals.length && !agentActionError) agentPanelOpen = false;
+      let panel = root.querySelector(".comty-agent-panel");
+      if (!panel && !agentPanelOpen) return;
+      if (!panel) {
+        panel = document.createElement("section");
+        panel.className = "comty-agent-panel";
+        panel.setAttribute("aria-label", "Local agent tasks");
+        panel.hidden = true;
+        // Keep the task card above inspection overlays and below the toolbar.
+        root.insertBefore(panel, toolbar);
+      }
+      const open = Boolean(agent) && agentPanelOpen;
+      if (open) {
+        clearAgentToast();
+        if (panel.hidden) {
+          const rect = toolbar.getBoundingClientRect();
+          panel.dataset.side = rect.left + rect.width / 2 < innerWidth / 2 ? "left" : "right";
+          panel.dataset.closed = "";
+          panel.hidden = false;
+          panel.getBoundingClientRect();
+        }
+        if (panel.hasAttribute("data-closed")) { agentPanelTransition++; delete panel.dataset.closed; }
+      } else if (!panel.hidden && !panel.hasAttribute("data-closed")) {
+        const transition = ++agentPanelTransition;
+        panel.dataset.closed = "";
+        const finish = () => { if (transition === agentPanelTransition && panel.hasAttribute("data-closed")) panel.hidden = true; };
+        if (reducedMotion.matches) finish();
+        else setTimeout(finish, parseFloat(getComputedStyle(root).getPropertyValue("--comty-motion-duration")));
+      }
+      panel.inert = !open;
+      panel.setAttribute("aria-hidden", String(!open));
+      const signature = JSON.stringify([visibleTasks, localApprovals, agentConnectionError, agentActionError, agentPanelOpen]);
+      if (signature === agentPanelSignature) return;
+      agentPanelSignature = signature;
+      const expanded = new Set([...panel.querySelectorAll('details[data-detail-key][open]')].map(node => node.dataset.detailKey));
+      const focusKey = panel.contains(document.activeElement) ? document.activeElement.dataset.focusKey : null;
+      const scrollTop = panel.querySelector('.comty-agent-panel-content')?.scrollTop || 0;
+      const node = (tag, className, text) => {
+        const element = document.createElement(tag);
+        if (className) element.className = className;
+        if (text != null) element.textContent = text;
+        return element;
+      };
+      const brand = () => createCommentAvatar({ author_kind: 'agent' }, 'comty-agent-brand');
+      panel.replaceChildren();
+      const header = node('header', 'comty-agent-panel-header');
+      const heading = node('div', 'comty-agent-heading');
+      heading.append(node('strong', '', 'Agent'));
+      const toggle = node('button', 'comty-agent-action comty-agent-close'); toggle.type = 'button';
+      toggle.innerHTML = icon('<path d="m6 6 12 12M6 18 18 6"/>');
+      toggle.setAttribute('aria-label', 'Close Agent task'); toggle.title = 'Close'; toggle.dataset.focusKey = 'close';
+      toggle.onclick = () => { agentPanelOpen = false; renderAgentPanel(); agentBtn?.focus({ preventScroll: true }); };
+      header.append(heading, toggle); panel.appendChild(header);
+      const content = node('div', 'comty-agent-panel-content'); panel.appendChild(content);
+      const technicalDetails = (parent, raw, key) => {
+        const details = node('details', 'comty-agent-details'); details.dataset.detailKey = key; details.open = expanded.has(key);
+        const summary = node('summary', '', 'Technical details'); summary.dataset.focusKey = 'details-' + key;
+        details.append(summary, node('pre', '', raw)); parent.appendChild(details);
+      };
+      const errorMessage = (parent, error, key) => {
+        const issue = describeAgentError(error);
+        const message = node('div', 'comty-agent-error');
+        message.append(node('strong', '', issue.title), node('p', '', issue.description));
+        parent.appendChild(message); technicalDetails(parent, issue.raw, key);
+      };
+      if (agentConnectionError || agentActionError) {
+        const banner = node('div', 'comty-agent-item comty-agent-banner'); banner.setAttribute('role', 'alert');
+        errorMessage(banner, agentConnectionError || agentActionError, 'connection'); content.appendChild(banner);
+      }
+      const action = (parent, label, path, input = {}, primary = false) => {
+        const button = node('button', 'comty-agent-action', label); button.type = 'button';
+        const key = path + JSON.stringify(input); button.dataset.focusKey = key;
+        button.disabled = agentPendingActions.has(key);
+        if (primary) button.dataset.primary = '';
+        button.onclick = async () => {
+          if (agentPendingActions.has(key)) return;
+          agentActionError = '';
+          agentPendingActions.add(key); button.disabled = true; button.textContent = 'Please wait…';
+          try {
+            await runAgentAction(path, input);
+          } catch (error) { agentActionError = error.message; }
+          finally { agentPendingActions.delete(key); agentPanelSignature = ''; renderAgentPanel(); }
+        };
+        parent.appendChild(button);
+      };
+      for (const approval of localApprovals) {
+        const section = node('div', 'comty-agent-item');
+        section.append(node('h3', '', 'Approval required'));
+        const task = localTasks.find(task => task.id === approval.taskId);
+        if (task) section.appendChild(node('p', '', task.content));
+        section.appendChild(node('p', '', 'Review this operation before allowing the agent to continue.'));
+        const operation = approval.details?.command || approval.details?.file_path || approval.details?.path;
+        if (typeof operation === 'string' || Array.isArray(operation)) section.appendChild(node('pre', '', Array.isArray(operation) ? operation.join(' ') : operation));
+        technicalDetails(section, JSON.stringify(approval.details ?? {}, null, 2), 'approval-' + approval.id);
+        const actions = node('div', 'comty-agent-actions');
+        action(actions, 'Allow once', `approvals/${approval.id}`, { allow: true }, true);
+        action(actions, 'Deny', `approvals/${approval.id}`, { allow: false });
+        section.appendChild(actions); content.appendChild(section);
+      }
+      const list = node('div', 'comty-agent-list'); content.appendChild(list);
+      for (const task of visibleTasks.reverse()) {
+        const failed = Boolean(task.error) || task.status === 'in_review';
+        const state = task.status === 'done' ? 'success' : failed ? 'error' : 'working';
+        const row = node('div', 'comty-agent-row'); row.dataset.taskId = task.id;
+        const dot = state === 'working' ? createWorkingIndicator() : node('span', 'comty-agent-dot');
+        dot.dataset.status = state; dot.setAttribute('aria-hidden', 'true');
+        const name = node('span', 'comty-agent-row-name', task.thread_comment_id ? `@Agent · ${task.content}` : task.content);
+        row.append(dot, name);
+        if (state === 'working') row.appendChild(node('span', 'comty-agent-row-state', task.status === 'todo' ? 'Starting' : 'Working'));
+        const actions = node('div', 'comty-agent-row-actions');
+        if (['in_review', 'cancel'].includes(task.status)) action(actions, 'Retry', `tasks/${task.id}/retry`);
+        if (['todo', 'in_progress'].includes(task.status)) action(actions, 'Cancel', `tasks/${task.id}/cancel`);
+        if (task.status === 'done') action(actions, 'Dismiss', `tasks/${task.id}/dismiss`);
+        if (task.status === 'in_review') action(actions, 'Dismiss', `tasks/${task.id}/dismiss`);
+        if (actions.childElementCount) row.appendChild(actions);
+        row.setAttribute('aria-label', `${task.content}, ${state === 'error' ? 'failed' : state === 'success' ? 'completed' : state === 'cancel' ? 'cancelled' : task.status === 'todo' ? 'starting' : 'working'}`);
+        list.appendChild(row);
+        if (task.error) {
+          const details = node('div', 'comty-agent-item');
+          errorMessage(details, task.error, task.id);
+          list.appendChild(details);
+        }
+        if (task.result?.summary) {
+          const answer = node('div', 'comty-agent-answer');
+          answer.append(brand(), node('p', '', task.result.summary));
+          list.appendChild(answer);
+        }
+      }
+      content.scrollTop = scrollTop;
+      if (focusKey && open) [...panel.querySelectorAll('[data-focus-key]')].find(element => element.dataset.focusKey === focusKey)?.focus({ preventScroll: true });
+    }
+
     function setSidepanelOpen(open) {
       sidepanelOpen = open;
       sidepanel.classList.toggle("comty-sidepanel-open", sidepanelOpen);
@@ -3048,12 +3537,52 @@ export function initComty(options = {}) {
 
     function openCommentFromPanel(comment) {
       const target = resolveCommentElement(comment);
-      if (!target || isElementTreeHidden(target)) return;
+      if (!target || isElementTreeHidden(target)) {
+        openDetachedThread(comment);
+        return;
+      }
       setSession(session.comments ? session.mode : "browse", { entry: sessionEntry, renderComments: true });
       target.scrollIntoView({ block: "center", inline: "nearest", behavior: "instant" });
+      const rect = target.getBoundingClientRect();
+      const relX = Number(comment.rel_x ?? comment.relX);
+      const relY = Number(comment.rel_y ?? comment.relY);
+      // Large page containers must reveal the annotation point, not their center.
+      window.scrollBy({
+        left: rect.width > innerWidth && Number.isFinite(relX) ? rect.left + Math.max(0, Math.min(1, relX)) * rect.width - innerWidth / 2 : 0,
+        top: rect.height > innerHeight && Number.isFinite(relY) ? rect.top + Math.max(0, Math.min(1, relY)) * rect.height - innerHeight / 2 : 0,
+        behavior: "instant",
+      });
       syncCommentAnchors();
       const pin = findPlacedPin(comment);
       if (pin && !pin.hasAttribute("data-comty-anchor-hidden")) pin.click();
+      else openDetachedThread(comment);
+    }
+
+    function openDetachedThread(comment) {
+      openCommentThread(comment, null, null, innerWidth / 2, innerHeight / 3, () => {});
+      const bubble = [...root.querySelectorAll(".comty-bubble")].find(node => node.dataset.commentId === String(comment.id));
+      if (bubble) {
+        bubble.dataset.detached = "";
+        positionCommentBubble(bubble, innerWidth / 2, innerHeight / 3);
+      }
+    }
+
+    function updateAnchorBadge(item, comment) {
+      resolveCommentElement(comment);
+      const result = commentTargets.get(String(comment.id));
+      const legacy = getPagePath() !== window.location.pathname && comment.page_path === window.location.pathname;
+      const status = legacy && !result?.element ? "uncertain" : result?.status;
+      const label = status === "missing" ? "Target missing" : status === "uncertain" ? "Target uncertain" : "";
+      let badge = item.querySelector(".comty-anchor-badge");
+      if (!label) { badge?.remove(); return; }
+      if (!badge) {
+        badge = document.createElement("span");
+        badge.className = "comty-anchor-badge";
+        item.querySelector(".comty-sidepanel-item-body").appendChild(badge);
+      }
+      if (badge.textContent !== label) badge.textContent = label;
+      badge.title = legacy ? "This older comment has no saved hash route. Its target may be on another page." :
+        status === "missing" ? "The target is not present on this page. The comment is still available." : "The target cannot be identified reliably. No pin is placed.";
     }
 
     let sidepanelFilters = { status: "", device: "", dateSort: "desc" };
@@ -3066,6 +3595,7 @@ export function initComty(options = {}) {
           ? sidepanelSearch.value.trim().toLowerCase()
           : "";
       let list = cachedComments.filter((comment) => {
+        if (comment.local_agent || comment.kind === "agent") return false;
         if (
           search &&
           !`${comment.content ?? ""} ${getCommentLabel(comment)}`
@@ -3112,6 +3642,7 @@ export function initComty(options = {}) {
         const item = document.createElement("button");
         item.type = "button";
         item.className = "comty-sidepanel-item";
+        item.dataset.commentId = String(comment.id);
         item.disabled = Boolean(comment.pending);
         item.innerHTML = `
         <span class="comty-sidepanel-item-status" aria-hidden="true"></span>
@@ -3135,8 +3666,13 @@ export function initComty(options = {}) {
         if (metaEl instanceof HTMLElement) {
           metaEl.innerText = `${comment.author_name || "Anonymous"} · ${comment.pending ? "Sending…" : getCommentLabel(comment)}`;
           metaEl.title = getCommentLabel(comment);
+          if (getPagePath() !== window.location.pathname && comment.page_path === window.location.pathname && !resolveCommentElement(comment)) {
+            metaEl.innerText += " · Original page unknown";
+          }
         }
 
+        updateAnchorBadge(item, comment);
+
         item.onclick = (event) => {
           event.stopPropagation();
           openCommentFromPanel(comment);
@@ -3206,7 +3742,7 @@ export function initComty(options = {}) {
           if (!(pin instanceof HTMLElement)) return;
           const status = pin.dataset.status;
           const shouldShow =
-            !hasFilters || Boolean(status && selectedStatusFilters.has(status));
+            pin.hasAttribute('data-agent-task') || !hasFilters || Boolean(status && selectedStatusFilters.has(status));
           pin.classList.toggle("comty-filtered-out", !shouldShow);
         });
     }
@@ -3252,14 +3788,15 @@ export function initComty(options = {}) {
     createStatusFilters();
 
     async function updateCommentStatus(comment, status) {
-      if (!projectId || !comment?.id) return false;
+      if (comment?.local_agent || !projectId || !comment?.id) return false;
 
       let res;
       try {
-        res = await fetch(`${apiUrl}/api/comments/${comment.id}/status`, {
+        const local = comment.local_agent === true;
+        res = await fetch(local ? `${agentBridgeUrl}/tasks/${encodeURIComponent(comment.id)}/status` : `${apiUrl}/api/comments/${comment.id}/status`, {
           method: "POST",
-          headers: getSdkHeaders({ "Content-Type": "application/json" }),
-          body: JSON.stringify({
+          headers: local ? { "Content-Type": "application/json" } : getSdkHeaders({ "Content-Type": "application/json" }),
+          body: JSON.stringify(local ? { status } : {
             projectKey,
             host: window.location.host,
             status,
@@ -3276,7 +3813,7 @@ export function initComty(options = {}) {
       }
 
       const data = await res.json();
-      comment.status = getCommentStatus(data.status).value;
+      comment.status = getCommentStatus(data.task?.status ?? data.status).value;
       return comment.status;
     }
 
@@ -3468,6 +4005,27 @@ export function initComty(options = {}) {
       isOwnCommentEntry, updateCommentContent, deleteSdkComment, getCommentId,
       updateReplyContent, deleteSdkReply, createCommentAvatar, getSdkHeaders,
       showAuthPrompt,
+      startThreadAgent: async (comment, replies, content) => {
+        if (!agent) throw new Error('Start the local agent to reply with @Agent');
+        if (!canManage) throw new Error('Sign in as a project editor to use @Agent');
+        const transcript = [
+          `${getCommentAuthorName(comment)}: ${comment.content}`,
+          ...replies.map(reply => `${getCommentAuthorName(reply)}: ${reply.content}`),
+        ].join('\n').slice(-24000);
+        const response = await fetch(`${agentBridgeUrl}/tasks`, {
+          method: 'POST', headers: agentHeaders(),
+          body: JSON.stringify({ content, pagePath: comment.page_path || getPagePath(),
+            selector: comment.selector || 'body', relX: comment.rel_x ?? 0.5, relY: comment.rel_y ?? 0.5,
+            domElement: comment.dom_element || '', viewport: comment.viewport || '',
+            anchorContext: comment.anchor_context || '', scope: 'element',
+            thread: { commentId: String(comment.id), transcript } }),
+        });
+        if (!response.ok) throw new Error((await response.json().catch(() => null))?.error || 'Could not start Agent');
+        const data = await response.json();
+        if (!data.task?.id) throw new Error('Agent returned no task ID');
+        requestedAgentTasks.add(data.task.id);
+        void loadComments({ force: true });
+      },
       get canWrite() { return canWrite; },
       get canManage() { return canManage; },
       get allowGuestComments() { return allowGuestComments; },
@@ -3582,6 +4140,7 @@ export function initComty(options = {}) {
 
       pin.onclick = (event) => {
         event.stopPropagation();
+        if (comment.local_agent) { openAgentTask(comment, getPinPoint(pin).x, getPinPoint(pin).y); return; }
         openCommentThread(
           comment,
           pin,
@@ -3668,42 +4227,122 @@ export function initComty(options = {}) {
     function reconcileComments(comments) {
       const previous = new Map(cachedComments.map(comment => [String(comment.id), comment]));
       cachedComments = comments
-        .filter(comment => comment.kind !== "agent" && !comment.local_agent)
+        .filter(comment => comment.kind !== "agent" || comment.status !== "done")
         .map(comment => Object.assign(previous.get(String(comment.id)) || {}, comment));
       for (const comment of previous.values()) {
         if (comment.pending && !cachedComments.some(item => item.id === comment.id)) cachedComments.push(comment);
       }
     }
 
-    async function loadComments({ force = false } = {}) {
-      if (!projectId) return;
-      const pagePath = window.location.pathname;
+    async function deliverThreadReply(task) {
+      if (deliveringAgentReplies.has(task.id)) return;
+      deliveringAgentReplies.add(task.id);
+      try {
+        const response = await fetch(`${apiUrl}/api/comments/${encodeURIComponent(task.thread_comment_id)}/replies`, {
+          method: 'POST', headers: getSdkHeaders({ 'Content-Type': 'application/json' }),
+          body: JSON.stringify({ projectKey, content: task.result.summary, agentTaskId: task.id }),
+        });
+        if (!response.ok) throw new Error(`Could not save Agent reply (${response.status})`);
+        const { reply } = await response.json();
+        const local = cachedComments.find(comment => String(comment.id) === task.thread_comment_id);
+        if (local && !local.replies?.some(item => item.id === reply.id)) {
+          local.replies ||= [];
+          local.replies.push(reply);
+        }
+        for (const bubble of root.querySelectorAll('.comty-bubble')) {
+          if (bubble.dataset.commentId === task.thread_comment_id) bubble.dispatchEvent(new CustomEvent('comty-agent-reply', { detail: reply }));
+        }
+        const ack = await fetch(`${agentBridgeUrl}/tasks/${task.id}/dismiss`, { method: 'POST', headers: agentHeaders(), body: '{}' });
+        if (!ack.ok) throw new Error('Agent reply saved, but local acknowledgement failed');
+        localTasks = localTasks.filter(item => item.id !== task.id);
+      } catch (error) {
+        agentActionError = error.message;
+        console.error('Comty: Agent reply delivery failed', error);
+      } finally {
+        deliveringAgentReplies.delete(task.id);
+        agentPanelSignature = '';
+        renderAgentPanel();
+      }
+    }
+
+    async function loadComments({ force = false, tasksOnly = false } = {}) {
+      if (!projectId && !agent) return;
+      const pagePath = getPagePath();
       if (!force && cachedPagePath === pagePath) { await renderComments(cachedComments); return; }
       if (pendingCommentsLoad) {
         await pendingCommentsLoad;
-        if (!force) return;
+        if (!force && cachedPagePath === pagePath) return;
       }
       pendingCommentsLoad = (async () => {
-        let comments = cachedPagePath === pagePath ? cachedComments : [];
-        if (projectId) {
+        let comments = cachedPagePath === pagePath ? cachedComments.filter(comment => !comment.local_agent) : [];
+        if (projectId && !tasksOnly) {
           try {
-            const url = new URL(`${apiUrl}/api/comments`);
-            url.search = new URLSearchParams({ projectKey, host: window.location.host, pagePath, ...(force ? { _t: String(Date.now()) } : {}) });
-            const res = await fetch(url);
-            if (!res.ok) throw new Error(await res.text());
-            const data = await res.json();
-            if (Array.isArray(data.comments)) comments = data.comments;
+            const paths = [...new Set([pagePath, window.location.pathname])];
+            const batches = await Promise.all(paths.map(async path => {
+              const url = new URL(`${apiUrl}/api/comments`);
+              url.search = new URLSearchParams({ projectKey, host: window.location.host, pagePath: path, ...(force ? { _t: String(Date.now()) } : {}) });
+              const res = await fetch(url);
+              if (!res.ok) throw new Error(await res.text());
+              const data = await res.json();
+              return Array.isArray(data.comments) ? data.comments : [];
+            }));
+            comments = [...new Map(batches.flat().map(comment => [String(comment.id), comment])).values()];
           } catch (error) { console.error("Comty: list comments failed", error); }
         }
+        if (agent) {
+          try {
+            const res = await fetch(`${agentBridgeUrl}/tasks`, { headers: agentHeaders(), cache: "no-store" });
+            if (!res.ok) throw new Error("Local companion unavailable");
+            const data = await res.json();
+            if (Array.isArray(data.tasks)) localTasks = data.tasks;
+            const failedTasks = localTasks.filter(task => task.status === 'in_review');
+            for (const task of failedTasks.filter(task => requestedAgentTasks.has(task.id))) {
+              if (task.error) showAgentBridgeError(task.error);
+              else showNotice({ title: 'Modification failed', description: 'The agent needs clarification.' });
+            }
+            if (Array.isArray(data.approvals)) {
+              localApprovals = data.approvals;
+              if (localApprovals.some(approval => requestedAgentTasks.has(approval.taskId) && !seenAgentApprovals.has(approval.id))) agentPanelOpen = true;
+              seenAgentApprovals.clear();
+              for (const approval of localApprovals) seenAgentApprovals.add(approval.id);
+            }
+            for (const id of requestedAgentTasks) {
+              const task = localTasks.find(task => task.id === id);
+              if (!task || ['done', 'cancel', 'in_review'].includes(task.status)) requestedAgentTasks.delete(id);
+            }
+            agentConnectionError = "";
+          } catch (error) {
+            agentConnectionError = "Local agent disconnected. Check the development server, then reload this page.";
+            console.error("Comty: local tasks failed", error);
+          }
+          for (const task of localTasks.filter(task => task.thread_comment_id && task.status === 'done' && task.result?.summary)) {
+            void deliverThreadReply(task);
+          }
+          comments.push(...localTasks.filter(task => task.page_path === pagePath && !task.thread_comment_id && task.status === 'in_review'));
+          renderAgentPanel();
+        }
+        if (pagePath !== getPagePath()) return;
         reconcileComments(comments);
         cachedPagePath = pagePath;
         renderSidepanelComments();
         await renderComments(cachedComments);
+        syncAgentWorkingOutlines();
         ensureLiveTracking();
       })();
       try { await pendingCommentsLoad; } finally { pendingCommentsLoad = null; }
     }
 
+    if (agent) {
+      setInterval(() => {
+        const active = requestedAgentTasks.size || localTasks.some(task =>
+          ['todo', 'in_progress'].includes(task.status) || (task.thread_comment_id && task.status === 'done' && task.result?.summary));
+        if (active && !pendingCommentsLoad && document.visibilityState === "visible") void loadComments({ force: true, tasksOnly: true });
+      }, 2000);
+      document.addEventListener('visibilitychange', () => {
+        if (document.visibilityState === 'visible' && !pendingCommentsLoad) void loadComments({ force: true, tasksOnly: true });
+      });
+    }
+
     function getPinPoint(pin) {
       return { x: parseFloat(pin.style.left), y: parseFloat(pin.style.top) };
     }
@@ -3731,7 +4370,7 @@ export function initComty(options = {}) {
     }
 
     function syncCommentAnchors() {
-      if (!session.comments) return;
+      if (!session.comments && !session.inspect) return;
       const modal = getTopActiveModal();
       for (const comment of cachedComments) {
         const id = String(comment.id);
@@ -3742,7 +4381,7 @@ export function initComty(options = {}) {
           placePin(comment, modal);
           pin = placedPins.get(id);
         }
-        const bubbles = [...root.querySelectorAll(".comty-bubble")].filter(bubble => bubble.dataset.commentId === id || bubble.dataset.hoverId === id);
+        const bubbles = [...root.querySelectorAll(".comty-bubble")].filter(bubble => (bubble.dataset.commentId === id || bubble.dataset.hoverId === id) && !bubble.hasAttribute("data-detached"));
         // A pin can remove its target's :hover style as the pointer enters it.
         if (!point && pin && target?.isConnected && !target.hasAttribute("hidden") && !isElementTreeHidden(target.parentElement) &&
           (activeHoverCommentIds.has(id) || bubbles.some(bubble => bubble.dataset.commentId === id))) continue;
@@ -3757,6 +4396,10 @@ export function initComty(options = {}) {
         if (pin.style.top !== y) pin.style.top = y;
         for (const bubble of bubbles) positionCommentBubble(bubble, point.clientX, point.clientY);
       }
+      if (sidepanelOpen) for (const item of sidepanelList.querySelectorAll(".comty-sidepanel-item")) {
+        const comment = cachedComments.find(comment => String(comment.id) === item.dataset.commentId);
+        if (comment) updateAnchorBadge(item, comment);
+      }
       if (draftAnchor) {
         if (!draftAnchor.target?.isConnected) draftAnchor.target = resolveCommentElement(draftAnchor.payload);
         const point = getVisibleAnchorPoint(draftAnchor.target, draftAnchor.payload.relX, draftAnchor.payload.relY, modal);
@@ -3770,16 +4413,50 @@ export function initComty(options = {}) {
       }
     }
 
+    function syncAgentWorkingOutlines() {
+      const working = localTasks.filter(task => task.status === "in_progress" && task.page_path === getPagePath());
+      const ids = new Set(working.map(task => String(task.id)));
+      for (const [id, outline] of workingOutlines) {
+        if (ids.has(id)) continue;
+        outline.remove(); workingOutlines.delete(id);
+      }
+      const modal = getTopActiveModal();
+      for (const task of working) {
+        const id = String(task.id);
+        let outline = workingOutlines.get(id);
+        if (!outline) {
+          outline = document.createElement("div");
+          outline.className = "comty-agent-working";
+          outline.setAttribute("aria-label", "Agent working on this element");
+          const badge = document.createElement("span");
+          badge.className = "comty-agent-working-badge";
+          badge.append(createWorkingIndicator(), "Working");
+          outline.appendChild(badge); root.appendChild(outline);
+          workingOutlines.set(id, outline);
+        }
+        const target = resolveCommentElement(task);
+        const point = target && getVisibleAnchorPoint(target, Number(task.rel_x), Number(task.rel_y), modal);
+        outline.hidden = !point;
+        if (!point) continue;
+        const rect = target.getBoundingClientRect();
+        setMeasuredRect(outline, rect);
+        outline.toggleAttribute("data-badge-below", rect.top < 32);
+      }
+    }
+
     function onFrame() {
       if (motion.enabled) updateMotion();
-      if (session.comments) syncCommentAnchors();
+      if (session.comments || session.inspect) syncCommentAnchors();
+      if (session.agent || workingOutlines.size || localTasks.some(task => task.status === "in_progress" && task.page_path === getPagePath())) {
+        syncAgentWorkingOutlines();
+      }
       if (session.inspect || session.edit || inspectionLayer.childNodes.length) renderInspector();
       if (session.inspect && rulersEnabled) renderRulers();
       if (session.inspect && rulersEnabled) measurements.render();
     }
 
     function ensureLiveTracking() {
-      const active = motion.enabled || session.inspect || session.edit || (session.comments && cachedComments.length > 0);
+      const active = motion.enabled || session.inspect || session.edit || (session.comments && cachedComments.length > 0) || workingOutlines.size > 0;
       if (!active || document.hidden) {
         if (liveFrame) cancelAnimationFrame(liveFrame);
         liveFrame = null;
@@ -3799,13 +4476,14 @@ export function initComty(options = {}) {
     syncOverlayHost();
 
     function renderCachedComments() {
-      if (!session.comments && !session.inspect && !session.edit) return;
+      if (!session.comments && !session.inspect && !session.edit && !workingOutlines.size) return;
       if (resizeRenderFrame) {
         window.cancelAnimationFrame(resizeRenderFrame);
       }
       resizeRenderFrame = window.requestAnimationFrame(() => {
         resizeRenderFrame = null;
         syncCommentAnchors();
+        syncAgentWorkingOutlines();
         renderInspector();
         ensureLiveTracking();
       });
@@ -3847,6 +4525,31 @@ export function initComty(options = {}) {
       characterData: true,
     });
 
+    let activePagePath = getPagePath();
+    function handleRouteChange() {
+      const next = getPagePath();
+      if (next === activePagePath) return;
+      activePagePath = next;
+      markup.clear();
+      markup.setMode(null);
+      closeBubbles();
+      commentTargets.clear();
+      reconcileComments([]);
+      void renderComments([], { retry: false });
+      renderSidepanelComments();
+      void loadComments({ force: true });
+    }
+    window.addEventListener("hashchange", handleRouteChange);
+    window.addEventListener("popstate", handleRouteChange);
+    for (const method of ["pushState", "replaceState"]) {
+      const original = history[method];
+      history[method] = function (...args) {
+        const result = original.apply(this, args);
+        handleRouteChange();
+        return result;
+      };
+    }
+
     document.addEventListener("scroll", handleHostLayoutEvent, {
       capture: true,
       passive: true,
@@ -3865,7 +4568,7 @@ export function initComty(options = {}) {
 
     document.addEventListener("pointermove", (event) => {
       if (!session.edit && !session.inspect) return;
-      if (motion.enabled) return;
+      if (motion.enabled || markup.mode) return;
       if (propertyPicking) {
         const target = event.target;
         if (propertyPicking === "font" && target instanceof Element && !isComtyElement(target) && getElementOwnTextSignature(target)) {
@@ -3984,13 +4687,14 @@ export function initComty(options = {}) {
         const y = e.clientY;
 
         const anchorContext = getAnchorContext(el);
+        if (session.agent && anchorContext) anchorContext.inspectedStyles = getInspectRows(el);
 
         const payload = {
           ...getDeviceContext(),
           projectId,
-          kind: "comment",
+          kind: session.agent ? "agent" : "comment",
           host: window.location.host,
-          pagePath: window.location.pathname,
+          pagePath: getPagePath(),
           selector: getSelector(el),
           relX,
           relY,
@@ -4011,6 +4715,12 @@ export function initComty(options = {}) {
         (target.isContentEditable ||
           ["INPUT", "TEXTAREA", "SELECT"].includes(target.tagName));
 
+      const markupMode = markup.mode;
+      if (session.inspect && (e.key === "Escape" || !isEditable) && markup.keydown(e)) {
+        e.preventDefault();
+        if (!markup.mode) (markupMode === "annotate" ? annotateBtn : screenshotBtn).focus({ preventScroll: true });
+        return;
+      }
       if (e.key === "Escape" && motion.enabled) {
         e.preventDefault();
         setMotionEnabled(false); motionBtn.focus({ preventScroll: true });
@@ -4025,7 +4735,7 @@ export function initComty(options = {}) {
         return;
       }
       if (session.inspect && !isEditable && !e.repeat && !e.ctrlKey && !e.metaKey && !e.altKey && !e.shiftKey) {
-        const button = { x: xrayBtn, r: rulersBtn, g: gridBtn, p: pipetteBtn, t: typographyBtn, m: motionBtn }[e.key.toLowerCase()];
+        const button = { x: xrayBtn, r: rulersBtn, g: gridBtn, p: pipetteBtn, t: typographyBtn, m: motionBtn, d: annotateBtn, s: screenshotBtn }[e.key.toLowerCase()];
         if (button) { e.preventDefault(); button.click(); return; }
       }
 
@@ -4033,6 +4743,11 @@ export function initComty(options = {}) {
         measureAlt = true;
         renderInspector();
       }
+      if (isLocalSite && !isEditable && !e.repeat && !e.isComposing && e.shiftKey && !e.altKey && !e.ctrlKey && !e.metaKey && e.key.toLowerCase() === "a") {
+        e.preventDefault();
+        startAgentSession();
+        return;
+      }
       if (!isEditable && !e.repeat && e.shiftKey && !e.altKey && !e.ctrlKey && !e.metaKey && e.key.toLowerCase() === "i") {
         e.preventDefault();
         setSession(session.inspect ? "off" : "inspect");
@@ -4088,6 +4803,7 @@ export function initComty(options = {}) {
     window.addEventListener("blur", () => { measureAlt = false; renderInspector(); });
 
     async function boot() {
+      if (localOnly) { await loadComments(); return; }
       const res = await fetch(`${apiUrl}/api/sdk/bootstrap`, {
         method: "POST",
         headers: getSdkHeaders({ "Content-Type": "application/json" }),
@@ -4100,6 +4816,7 @@ export function initComty(options = {}) {
 
       if (!res.ok) {
         console.error("Comty: bootstrap failed", await res.text());
+        if (agent) await loadComments();
         return;
       }
 
@@ -4144,16 +4861,30 @@ export function initComty(options = {}) {
 
     if (typeof options.onTestReady === "function") {
       options.onTestReady({
-        getSelector, getAnchorContext, resolveCommentElement, getVisibleAnchorPoint,
+        getPagePath, getSelector, getAnchorContext, resolveCommentElement, getVisibleAnchorPoint,
         getDistanceSegments, getInspectRows, syncCommentAnchors,
         setInspectorMode(enabled) { setSession(enabled ? "inspect" : "off"); },
         startEditSession, startBrowseSession, endSession, showInspector,
-        motion, setMotionEnabled, updateMotion,
+        motion, setMotionEnabled, updateMotion, describeAgentError,
+        previewAgent(tasks, approvals = [], error = "") {
+          localTasks = tasks;
+          localApprovals = approvals;
+          agentConnectionError = error;
+          startAgentSession();
+          agentPanelOpen = true;
+          agentPanelSignature = "";
+          renderAgentPanel();
+        },
         seed(comments) {
           reconcileComments(comments);
           setSession(session.comments ? session.mode : "browse", { entry: sessionEntry, renderComments: true });
           return renderComments(cachedComments, { retry: false });
         },
+        seedAgentTasks(tasks) {
+          localTasks = tasks;
+          syncAgentWorkingOutlines();
+          ensureLiveTracking();
+        },
         setCanWrite(value) { canWrite = value; canManage = value; },
         invalidate() { anchorRevision += 1; },
       });
@@ -4161,6 +4892,7 @@ export function initComty(options = {}) {
 
     return boot().catch(error => {
       console.error("Comty: bootstrap failed", error);
+      if (agent) return loadComments();
     });
   }
 }