@comty.io/core 0.1.5 → 0.1.7

package/package.json

@@ -1,17 +1,24 @@
 {
   "name": "@comty.io/core",
-  "version": "0.1.5",
-  "description": "Comty visual comments and inspector",
+  "version": "0.1.7",
+  "description": "Comty visual comments, inspector and local agent tools",
   "type": "module",
   "license": "UNLICENSED",
   "engines": {
     "node": ">=22.12"
   },
   "sideEffects": false,
+  "bin": {
+    "comty": "src/dev.mjs"
+  },
   "exports": {
     ".": {
       "types": "./src/browser.d.ts",
       "import": "./src/browser.js"
+    },
+    "./vite": {
+      "types": "./src/vite.d.ts",
+      "import": "./src/vite.mjs"
     }
   },
   "files": [
@@ -25,14 +32,18 @@
   "scripts": {
     "build": "node scripts/build.mjs",
     "check:build": "node scripts/build.mjs --check",
-    "test": "node --test tests/measurements.test.mjs tests/anchors.test.mjs tests/package.test.mjs tests/packed.test.mjs",
+    "test": "node --experimental-websocket --test tests/measurements.test.mjs tests/anchors.test.mjs tests/package.test.mjs tests/packed.test.mjs tests/companion.test.mjs tests/codex.test.mjs tests/claude.test.mjs tests/cursor.test.mjs tests/acp.test.mjs",
     "test:capture": "node --test tests/capture.browser.test.mjs",
-    "test:inspector": "node --test tests/inspector.browser.test.mjs",
+    "test:inspector": "node --test tests/inspector.browser.test.mjs tests/inspect-markup.browser.test.mjs tests/idle-network.browser.test.mjs",
+    "test:placement": "node --test tests/placement.browser.test.mjs",
+    "test:anchors": "node --test tests/anchors.test.mjs tests/anchor-reload.browser.test.mjs",
+    "test:vite": "node --test tests/vite.test.mjs",
     "prepack": "npm run build"
   },
   "devDependencies": {
-    "esbuild": "0.25.12",
+    "esbuild": "0.28.2",
     "html-to-image": "1.11.13",
-    "playwright": "1.55.1"
+    "playwright": "1.55.1",
+    "vite": "8.1.5"
   }
 }

package/src/acp.mjs

@@ -0,0 +1,68 @@
+import { realpathSync } from 'node:fs';
+import { openAgentProcess } from './agent-process.mjs';
+import { parseReceipt, receiptSchema, taskPrompt } from './codex.mjs';
+
+const agents = {
+  gemini: { executable: 'gemini', command: ['--acp'], label: 'Gemini' },
+  grok: { executable: 'grok', command: ['--no-auto-update', 'agent', 'stdio'], label: 'Grok' },
+};
+
+export async function runAcp({ provider, cwd, task, signal, approve, progress, model, executable, args = [] }) {
+  const agent = agents[provider];
+  if (!agent) throw new Error(`Unsupported ACP agent: ${provider}`);
+  cwd = realpathSync(cwd);
+  let output = '';
+  let resolveReceipt;
+  const receiptReady = new Promise(resolve => { resolveReceipt = resolve; });
+  const rpc = openAgentProcess({
+    executable: executable || agent.executable, args: [...args, ...(model ? ['--model', model] : []), ...agent.command], cwd, signal, label: agent.label,
+    async onRequest(method, params) {
+      if (method === 'session/request_permission') {
+        const allow = await approve({ type: method, details: params.toolCall });
+        const option = params.options?.find(item => item.kind === (allow ? 'allow_once' : 'reject_once'));
+        return { outcome: option ? { outcome: 'selected', optionId: option.optionId } : { outcome: 'cancelled' } };
+      }
+      throw new Error(`${agent.label} needs an unsupported interaction: ${method}`);
+    },
+    onNotification(method, params) {
+      if (method !== 'session/update' || params?.update?.sessionUpdate !== 'agent_message_chunk') return;
+      if (params.update.content?.type === 'text') {
+        output += params.update.content.text;
+        if (output.length > 1024 * 1024) throw new Error(`${agent.label} response exceeded 1 MiB`);
+        progress(output.slice(-4000));
+        if (output.trimEnd().endsWith('</comty_result>')) resolveReceipt();
+      }
+    },
+  });
+  try {
+    const init = await rpc.request('initialize', {
+      protocolVersion: 1, clientInfo: { name: 'comty', version: '0.1.0' },
+      clientCapabilities: { fs: { readTextFile: false, writeTextFile: false }, terminal: false },
+    });
+    const authMethods = new Set(init?.authMethods?.map(method => method.id) || []);
+    const methodId = provider === 'gemini' ? (process.env.GEMINI_API_KEY && authMethods.has('gemini-api-key') ? 'gemini-api-key' : 'oauth-personal')
+      : (process.env.XAI_API_KEY && authMethods.has('xai.api_key') ? 'xai.api_key' : 'cached_token');
+    if (provider === 'grok' && !authMethods.has(methodId)) throw new Error('Run grok login first, or set XAI_API_KEY');
+    if (provider === 'gemini' && !authMethods.has(methodId)) throw new Error('Sign in to Gemini CLI first, or set GEMINI_API_KEY');
+    await rpc.request('authenticate', { methodId, ...(provider === 'grok' ? { _meta: { headless: true } } : {}) });
+    const session = await rpc.request('session/new', { cwd, mcpServers: [] });
+    if (!session?.sessionId) throw new Error(`${agent.label} did not create a session`);
+    const result = await rpc.request('session/prompt', {
+      sessionId: session.sessionId,
+      prompt: [{ type: 'text', text: `${taskPrompt(task)}\n\nEnd your final response with <comty_result>JSON</comty_result>. The JSON must match this schema: ${JSON.stringify(receiptSchema)}. Write nothing after the closing tag.` }],
+    }, 0);
+    if (result?.stopReason !== 'end_turn') throw new Error(`${agent.label} stopped: ${result?.stopReason || 'unknown reason'}`);
+    if (!output.trimEnd().endsWith('</comty_result>')) {
+      let timeout;
+      try {
+        await Promise.race([receiptReady, new Promise((_, reject) => {
+          timeout = setTimeout(() => reject(new Error(`${agent.label} did not return a completion receipt`)), 2000);
+        })]);
+      } finally { clearTimeout(timeout); }
+    }
+    const text = output.trim();
+    const start = text.lastIndexOf('<comty_result>');
+    if (start < 0 || !text.endsWith('</comty_result>')) throw new Error(`${agent.label} did not return a completion receipt`);
+    return parseReceipt(text.slice(start + '<comty_result>'.length, -'</comty_result>'.length));
+  } finally { await rpc.close(); }
+}

package/src/agent-process.mjs

@@ -0,0 +1,89 @@
+import { spawn } from 'node:child_process';
+
+// Codex app-server and ACP agents use newline-delimited JSON-RPC on stdio.
+export function openAgentProcess({ executable, args, cwd, signal, label, onRequest, onNotification }) {
+  signal.throwIfAborted();
+  const child = spawn(executable, args, { cwd, stdio: ['pipe', 'pipe', 'pipe'], detached: process.platform !== 'win32' });
+  const pending = new Map();
+  let nextId = 0, buffer = '', stderr = '', closed = false, failureError, closing, rejectFailure;
+  const failure = new Promise((_, reject) => { rejectFailure = reject; });
+  failure.catch(() => {});
+  const exited = new Promise(resolve => child.once('close', () => { closed = true; resolve(); }));
+  function fail(error) {
+    failureError ||= error;
+    rejectFailure(failureError);
+    for (const waiter of pending.values()) { clearTimeout(waiter.timeout); waiter.reject(failureError); }
+    pending.clear();
+  }
+  function send(value) {
+    if (failureError) throw failureError;
+    if (closed || child.stdin.destroyed) throw new Error(`${label} connection closed`);
+    child.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', ...value })}\n`);
+  }
+  async function receive(message) {
+    if (message.method && message.id !== undefined) {
+      try { send({ id: message.id, result: await onRequest(message.method, message.params) }); }
+      catch (error) {
+        if (!failureError) send({ id: message.id, error: { code: -32603, message: error.message } });
+        throw error;
+      }
+    } else if (message.id !== undefined) {
+      const waiter = pending.get(message.id);
+      if (!waiter) return;
+      clearTimeout(waiter.timeout); pending.delete(message.id);
+      if (message.error) waiter.reject(new Error(message.error.message || `${label} request failed`));
+      else waiter.resolve(message.result);
+    } else if (message.method) await onNotification(message.method, message.params);
+  }
+  child.stdout.setEncoding('utf8');
+  child.stdout.on('data', chunk => {
+    buffer += chunk;
+    if (buffer.length > 8 * 1024 * 1024) return fail(new Error(`${label} output exceeded the message limit`));
+    let index;
+    while ((index = buffer.indexOf('\n')) !== -1) {
+      const line = buffer.slice(0, index); buffer = buffer.slice(index + 1);
+      if (!line.trim()) continue;
+      try { void receive(JSON.parse(line)).catch(fail); } catch (error) { fail(error); }
+    }
+  });
+  child.stderr.on('data', chunk => { stderr = (stderr + chunk).slice(-4000); });
+  child.stdin.on('error', fail);
+  child.on('error', error => fail(new Error(`Cannot start ${label}: ${error.message}. Install and sign in to its CLI.`)));
+  child.on('close', code => fail(new Error(`${label} exited (${code}): ${stderr || 'connection closed'}`)));
+  const abort = () => fail(signal.reason || new Error('Task cancelled'));
+  signal.addEventListener('abort', abort, { once: true });
+  return {
+    failure,
+    notify: (method, params) => send({ method, params }),
+    request(method, params, timeoutMs = 30_000) {
+      return new Promise((resolve, reject) => {
+        signal.throwIfAborted();
+        if (failureError) throw failureError;
+        const id = ++nextId;
+        const timeout = timeoutMs ? setTimeout(() => {
+          pending.delete(id); reject(new Error(`${label} timed out: ${method}`));
+        }, timeoutMs) : undefined;
+        pending.set(id, { resolve, reject, timeout });
+        try { send({ id, method, params }); } catch (error) {
+          clearTimeout(timeout); pending.delete(id); reject(error);
+        }
+      });
+    },
+    close() {
+      if (closing) return closing;
+      signal.removeEventListener('abort', abort);
+      fail(new Error(`${label} session closed`));
+      const kill = signalName => {
+        if (closed) return;
+        try {
+          if (process.platform === 'win32') child.kill(signalName);
+          else if (child.pid) process.kill(-child.pid, signalName);
+        } catch (error) { if (error.code !== 'ESRCH') throw error; }
+      };
+      kill('SIGTERM');
+      const timer = setTimeout(() => kill('SIGKILL'), 2000);
+      closing = exited.finally(() => clearTimeout(timer));
+      return closing;
+    },
+  };
+}

package/src/anchors.js

@@ -11,6 +11,14 @@ export function createAnchorMatcher({
       return haystack.toLowerCase().includes(needle.toLowerCase());
     }
 
+    function similarText(a, b) {
+      if (!a || !b) return false;
+      const words = value => new Set(value.toLowerCase().split(/\s+/).filter(Boolean));
+      const left = words(a), right = words(b);
+      const common = [...left].filter(word => right.has(word)).length;
+      return common >= 2 && common / Math.max(left.size, right.size) >= 0.7;
+    }
+
     function scoreFingerprint(el, fingerprint) {
       if (!el || !fingerprint) return 0;
       if (
@@ -80,6 +88,8 @@ export function createAnchorMatcher({
         score += 15;
       }
 
+      if (text !== fingerprint.text && similarText(text, fingerprint.text)) score += 24;
+
       if (typeof fingerprint.siblingIndex === "number" && el.parentElement) {
         const siblings = [...el.parentElement.children].filter(
           (child) => child.tagName === el.tagName,
@@ -157,6 +167,8 @@ export function createAnchorMatcher({
         if (ancestorScore > 0) {
           score += Math.min(ancestorScore, 40) * (index === 0 ? 0.5 : 0.2);
         }
+        // Distinguish repeated cards by their section, even when dimensions match.
+        if (index < 3 && ancestors[index].text && getElementTextSignature(parent) === ancestors[index].text) score += 18;
         parent = parent.parentElement;
       }
 
@@ -171,46 +183,75 @@ export function createAnchorMatcher({
       return score;
     }
 
-    function matchesAnchorIdentity(el, fingerprint) {
+    function matchesAnchorIdentity(el, fingerprint, ignoreDescendantText = false, allowTextChanges = true) {
       if (!el || !fingerprint || el.tagName.toLowerCase() !== fingerprint.tag) return false;
       const attributes = { ariaLabel: "aria-label", name: "name", href: "href", src: "src", alt: "alt", title: "title", role: "role" };
       for (const [key, attribute] of Object.entries(attributes)) {
         if (fingerprint[key] && getAttributeSignature(el, attribute) !== fingerprint[key]) return false;
       }
-      if (fingerprint.ownText && getElementOwnTextSignature(el) !== fingerprint.ownText) return false;
+      if (fingerprint.id && el.id !== fingerprint.id) return false;
+      if (fingerprint.testId && !["data-testid", "data-test", "data-cy"].some(name => getAttributeSignature(el, name) === fingerprint.testId)) return false;
+      const stableIdentity = (fingerprint.id && el.id === fingerprint.id) ||
+        (fingerprint.testId && ["data-testid", "data-test", "data-cy"].some(name => getAttributeSignature(el, name) === fingerprint.testId));
+      if (fingerprint.ownText && getElementOwnTextSignature(el) !== fingerprint.ownText && !(allowTextChanges && stableIdentity)) return false;
       // Container text is useful for matching remounted drawers and dialogs.
-      if (!fingerprint.ownText && fingerprint.text && getElementTextSignature(el) !== fingerprint.text) return false;
+      if (!ignoreDescendantText && !fingerprint.ownText && fingerprint.text && getElementTextSignature(el) !== fingerprint.text && !(allowTextChanges && stableIdentity)) {
+        if (!allowTextChanges || !el.children.length || !similarText(getElementTextSignature(el), fingerprint.text)) return false;
+      }
       return true;
     }
 
     function matchesAnchorContext(el, context) {
       if (!context) return true;
-      if (!matchesAnchorIdentity(el, context.target)) return false;
+      // A unique page landmark keeps its identity when a child is edited.
+      const pageContainer = !context.layer && (context.target?.tag === "main" || context.target?.role === "main") &&
+        [...document.querySelectorAll('main, [role="main"]')].filter(node => !isComtyNode(node)).length === 1;
+      if (!matchesAnchorIdentity(el, context.target, pageContainer)) return false;
       const parentFingerprint = context.ancestors?.[0];
       if (parentFingerprint?.text && parentFingerprint.text !== context.target.text &&
-          !matchesAnchorIdentity(el.parentElement, parentFingerprint)) return false;
+          !matchesAnchorIdentity(el.parentElement, parentFingerprint, pageContainer)) return false;
       const layer = getPresentationLayer(el);
-      if (context.layer && (!layer || !matchesAnchorIdentity(layer, context.layer))) return false;
+      if (context.layer && (!layer || !matchesAnchorIdentity(layer, context.layer, false, false))) return false;
       if (context.version >= 2 && !context.layer && layer) return false;
       return scoreAnchorCandidate(el, context) >= 50;
     }
 
-    function resolveByAnchorContext(context) {
-      if (!context?.target) return null;
+    function resolveAnchor(context, exact = null) {
+      if (!context?.target) return { element: exact, status: exact ? "matched" : "missing" };
       let candidates;
       try {
-        candidates = [...document.body.querySelectorAll(context.target.tag || "*")];
+        candidates = [...document.body.querySelectorAll(context.target.tag || "*")].filter(el => !isComtyNode(el));
       } catch {
-        return null;
+        return { element: null, status: "missing" };
       }
       const matches = candidates
-        .filter(el => !isComtyNode(el) && matchesAnchorContext(el, context))
-        .map(el => ({ el, score: scoreAnchorCandidate(el, context) }))
+        .filter(el => matchesAnchorContext(el, context))
+        .map(el => ({ el, score: scoreAnchorCandidate(el, context) + (context.version === 1 && el === exact ? 16 : 0) }))
         .sort((a, b) => b.score - a.score);
-      if (!matches.length || matches[0].score < 58) return null;
-      // ponytail: ambiguous remounts stay hidden; explicit reattachment can handle identical twins later.
-      if (matches[1] && matches[0].score - matches[1].score < 12) return null;
-      return matches[0].el;
+      if (context.candidateCount > 1) {
+        const peers = candidates.filter(el => matchesAnchorIdentity(el, context.target));
+        if (peers.length !== context.candidateCount) {
+          // A removed identical sibling must not move its comment to the survivor.
+          const distinctive = matches[0] && (context.target.id || context.target.testId);
+          if (!distinctive) return { element: null, status: "uncertain" };
+        }
+      }
+      if (matches[0]?.score >= 58 && (!matches[1] || matches[0].score - matches[1].score >= 12)) {
+        return { element: matches[0].el, status: "matched" };
+      }
+      // A closed/unmounted overlay is not evidence that its contents were deleted.
+      if (context.layer && !candidates.some(el => {
+        const layer = getPresentationLayer(el);
+        return layer && matchesAnchorIdentity(layer, context.layer, false, false);
+      })) return { element: null, status: "hidden" };
+      const plausible = matches.length || candidates.some(el =>
+        (context.target.id && el.id === context.target.id) ||
+        (context.target.text && (getElementTextSignature(el) === context.target.text || similarText(getElementTextSignature(el), context.target.text))));
+      return { element: null, status: plausible ? "uncertain" : "missing" };
+    }
+
+    function resolveByAnchorContext(context) {
+      return resolveAnchor(context).element;
     }
 
     function getViewportBounds() {
@@ -382,5 +423,5 @@ export function createAnchorMatcher({
       return { clientX, clientY };
     }
 
-    return { matchesAnchorContext, resolveByAnchorContext, isElementTreeHidden, getTopActiveModal, getVisibleAnchorPoint };
+    return { matchesAnchorContext, resolveAnchor, resolveByAnchorContext, isElementTreeHidden, getTopActiveModal, getVisibleAnchorPoint };
 }

package/src/browser.d.ts

@@ -1,8 +1,10 @@
 export interface ComtyOptions {
   /** Project key from your Comty dashboard. */
-  projectKey: string;
+  projectKey?: string;
   /** Absolute URL of your Comty API. Defaults to http://localhost:4000. */
   apiUrl?: string;
+  /** Set automatically by comty dev; not needed in application code. */
+  agent?: { url: string; token: string };
 }
 
 /**