npm - @yuzc-001/grasp - Versions diffs - 0.6.6 - Mend

@yuzc-001/grasp 0.6.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (78) hide show

package/LICENSE +21 -0
package/README.md +327 -0
package/README.zh-CN.md +324 -0
package/examples/README.md +31 -0
package/examples/claude-desktop.json +8 -0
package/examples/codex-config.toml +4 -0
package/grasp.skill +0 -0
package/index.js +87 -0
package/package.json +48 -0
package/scripts/grasp_openclaw_ctl.sh +122 -0
package/scripts/run-search-benchmark.mjs +287 -0
package/scripts/update-star-history.mjs +274 -0
package/skill/SKILL.md +61 -0
package/skill/references/tools.md +306 -0
package/src/cli/auto-configure.js +116 -0
package/src/cli/cmd-connect.js +148 -0
package/src/cli/cmd-explain.js +42 -0
package/src/cli/cmd-logs.js +55 -0
package/src/cli/cmd-status.js +119 -0
package/src/cli/config.js +27 -0
package/src/cli/detect-chrome.js +58 -0
package/src/grasp/handoff/events.js +67 -0
package/src/grasp/handoff/persist.js +48 -0
package/src/grasp/handoff/state.js +28 -0
package/src/grasp/page/capture.js +34 -0
package/src/grasp/page/state.js +273 -0
package/src/grasp/verify/evidence.js +40 -0
package/src/grasp/verify/pipeline.js +52 -0
package/src/layer1-bridge/chrome.js +416 -0
package/src/layer1-bridge/webmcp.js +143 -0
package/src/layer2-perception/hints.js +284 -0
package/src/layer3-action/actions.js +400 -0
package/src/runtime/browser-instance.js +65 -0
package/src/runtime/truth/model.js +94 -0
package/src/runtime/truth/snapshot.js +51 -0
package/src/server/affordances.js +47 -0
package/src/server/audit.js +122 -0
package/src/server/boss-fast-path.js +164 -0
package/src/server/boundary-guard.js +53 -0
package/src/server/content.js +97 -0
package/src/server/continuity.js +256 -0
package/src/server/engine-selection.js +29 -0
package/src/server/entry-orchestrator.js +115 -0
package/src/server/error-codes.js +7 -0
package/src/server/explain-share-card.js +113 -0
package/src/server/fast-path-router.js +134 -0
package/src/server/form-runtime.js +602 -0
package/src/server/form-tasks.js +254 -0
package/src/server/gateway-response.js +62 -0
package/src/server/index.js +22 -0
package/src/server/observe.js +52 -0
package/src/server/page-projection.js +31 -0
package/src/server/page-state.js +27 -0
package/src/server/postconditions.js +128 -0
package/src/server/prompt-assembly.js +148 -0
package/src/server/responses.js +44 -0
package/src/server/route-boundary.js +174 -0
package/src/server/route-policy.js +168 -0
package/src/server/runtime-confirmation.js +87 -0
package/src/server/runtime-status.js +7 -0
package/src/server/share-artifacts.js +284 -0
package/src/server/state.js +132 -0
package/src/server/structured-extraction.js +131 -0
package/src/server/surface-prompts.js +166 -0
package/src/server/task-frame.js +11 -0
package/src/server/tasks/search-task.js +321 -0
package/src/server/tools.actions.js +1361 -0
package/src/server/tools.form.js +526 -0
package/src/server/tools.gateway.js +757 -0
package/src/server/tools.handoff.js +210 -0
package/src/server/tools.js +20 -0
package/src/server/tools.legacy.js +983 -0
package/src/server/tools.strategy.js +250 -0
package/src/server/tools.task-surface.js +66 -0
package/src/server/tools.workspace.js +873 -0
package/src/server/workspace-runtime.js +1138 -0
package/src/server/workspace-tasks.js +735 -0
package/start-chrome.bat +84 -0

package/src/server/share-artifacts.js ADDED Viewed

@@ -0,0 +1,284 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+const DEFAULT_ARTIFACT_DIR = path.join(os.homedir(), '.grasp', 'artifacts');
+function toSafeText(value) {
+  return String(value ?? '').trim();
+}
+export function escapeHtml(value) {
+  return String(value ?? '')
+    .replaceAll('&', '&amp;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&#39;');
+}
+export function buildShareMarkdown({ projection, explainCard } = {}) {
+  const title = toSafeText(projection?.title) || 'Untitled';
+  const url = toSafeText(projection?.url) || 'unknown';
+  const summary = toSafeText(projection?.summary);
+  const mainText = toSafeText(projection?.main_text);
+  const lines = [
+    `# ${title}`,
+    '',
+    `Source: ${url}`,
+  ];
+  if (summary) {
+    lines.push('', '## Summary', '', summary);
+  }
+  if (mainText) {
+    lines.push('', '## Content', '', mainText);
+  }
+  if (explainCard) {
+    lines.push(
+      '',
+      '## Share Card',
+      '',
+      `- Engine: ${explainCard.engine}`,
+      `- Estimated height: ${explainCard.estimated_height}px`,
+      `- Title lines: ${explainCard.title_lines}`,
+      `- Summary lines: ${explainCard.summary_lines}`,
+      `- Body lines: ${explainCard.body_lines}`,
+    );
+  }
+  return lines.join('\n').trim();
+}
+export function buildBatchMarkdownBundle({ fields = [], records = [] } = {}) {
+  const lines = ['# Batch Extract', ''];
+  for (const record of records) {
+    const title = toSafeText(record?.title) || 'Untitled';
+    lines.push(`## ${title}`);
+    lines.push('');
+    lines.push(`- Input URL: ${toSafeText(record?.input_url) || 'unknown'}`);
+    lines.push(`- Final URL: ${toSafeText(record?.final_url) || 'unknown'}`);
+    lines.push(`- Status: ${toSafeText(record?.status) || 'unknown'}`);
+    for (const field of fields) {
+      lines.push(`- ${field}: ${toSafeText(record?.record?.[field]) || ''}`);
+    }
+    if (Array.isArray(record?.missing_fields) && record.missing_fields.length > 0) {
+      lines.push(`- Missing fields: ${record.missing_fields.join(', ')}`);
+    }
+    lines.push('');
+  }
+  return lines.join('\n').trim();
+}
+export function serializeCsv(columns = [], rows = []) {
+  const escapeCell = (value) => {
+    const cell = String(value ?? '');
+    if (cell.includes('"') || cell.includes(',') || cell.includes('\n')) {
+      return `"${cell.replaceAll('"', '""')}"`;
+    }
+    return cell;
+  };
+  const csvRows = [
+    columns.map(escapeCell).join(','),
+    ...rows.map((row) => columns.map((column) => escapeCell(row?.[column])).join(',')),
+  ];
+  return csvRows.join('\n');
+}
+export function buildShareHtml({ projection, explainCard } = {}) {
+  const title = toSafeText(projection?.title) || 'Untitled';
+  const url = toSafeText(projection?.url) || 'unknown';
+  const summary = toSafeText(projection?.summary);
+  const mainText = toSafeText(projection?.main_text);
+  const headerHeight = Math.max(240, Number(explainCard?.estimated_height ?? 0));
+  return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <title>${escapeHtml(title)}</title>
+    <style>
+      :root {
+        color-scheme: light;
+        --page-width: 860px;
+        --ink: #0b1738;
+        --muted: #52607a;
+        --line: #d9e0ef;
+        --card: #ffffff;
+        --wash: linear-gradient(180deg, #eef5ff 0%, #f9fbff 100%);
+        --accent: #23c993;
+      }
+      * { box-sizing: border-box; }
+      body {
+        margin: 0;
+        padding: 40px;
+        font-family: Arial, sans-serif;
+        background: radial-gradient(circle at top left, #dff6ea 0%, #eef5ff 42%, #f8fbff 100%);
+        color: var(--ink);
+      }
+      .sheet {
+        width: min(100%, var(--page-width));
+        margin: 0 auto;
+        background: var(--card);
+        border: 1px solid var(--line);
+        border-radius: 28px;
+        overflow: hidden;
+        box-shadow: 0 24px 80px rgba(11, 23, 56, 0.12);
+      }
+      .hero {
+        min-height: ${headerHeight}px;
+        padding: 40px 44px 28px;
+        background: var(--wash);
+        border-bottom: 1px solid var(--line);
+      }
+      .eyebrow {
+        display: inline-block;
+        padding: 8px 14px;
+        border-radius: 999px;
+        background: rgba(35, 201, 147, 0.12);
+        color: #0d7d5d;
+        font-size: 13px;
+        font-weight: 700;
+        letter-spacing: 0.04em;
+        text-transform: uppercase;
+      }
+      h1 {
+        margin: 18px 0 14px;
+        font-size: 34px;
+        line-height: 1.2;
+      }
+      .summary {
+        margin: 0;
+        color: var(--muted);
+        font-size: 18px;
+        line-height: 1.55;
+      }
+      .meta {
+        margin-top: 20px;
+        color: var(--muted);
+        font-size: 14px;
+        line-height: 1.6;
+      }
+      .body {
+        padding: 32px 44px 44px;
+        white-space: pre-wrap;
+        font-size: 16px;
+        line-height: 1.7;
+      }
+      .layout {
+        margin-top: 28px;
+        display: grid;
+        grid-template-columns: repeat(4, minmax(0, 1fr));
+        gap: 12px;
+      }
+      .layout-card {
+        padding: 14px 16px;
+        border-radius: 18px;
+        border: 1px solid var(--line);
+        background: rgba(255, 255, 255, 0.78);
+      }
+      .layout-card strong {
+        display: block;
+        font-size: 12px;
+        text-transform: uppercase;
+        color: var(--muted);
+        margin-bottom: 6px;
+      }
+      .layout-card span {
+        font-size: 18px;
+        font-weight: 700;
+      }
+    </style>
+  </head>
+  <body>
+    <main class="sheet">
+      <section class="hero">
+        <div class="eyebrow">Grasp Share</div>
+        <h1>${escapeHtml(title)}</h1>
+        <p class="summary">${escapeHtml(summary || mainText.slice(0, 160))}</p>
+        <div class="meta">Source: ${escapeHtml(url)}</div>
+        <div class="layout">
+          <div class="layout-card"><strong>Engine</strong><span>${escapeHtml(explainCard?.engine ?? 'fallback')}</span></div>
+          <div class="layout-card"><strong>Height</strong><span>${escapeHtml(String(explainCard?.estimated_height ?? 0))}px</span></div>
+          <div class="layout-card"><strong>Title Lines</strong><span>${escapeHtml(String(explainCard?.title_lines ?? 0))}</span></div>
+          <div class="layout-card"><strong>Summary Lines</strong><span>${escapeHtml(String(explainCard?.summary_lines ?? 0))}</span></div>
+        </div>
+      </section>
+      <section class="body">${escapeHtml(mainText)}</section>
+    </main>
+  </body>
+</html>`;
+}
+async function defaultCreateScratchPage(page) {
+  const context = page?.context?.();
+  if (!context || typeof context.newPage !== 'function') {
+    throw new Error('Share rendering requires a browser page context.');
+  }
+  return context.newPage();
+}
+export async function renderShareArtifact(page, html, format, deps = {}) {
+  const createScratchPage = deps.createScratchPage ?? defaultCreateScratchPage;
+  const scratchPage = await createScratchPage(page);
+  try {
+    if (typeof scratchPage.setViewportSize === 'function') {
+      await scratchPage.setViewportSize({ width: 960, height: 1280 });
+    }
+    await scratchPage.setContent(html, { waitUntil: 'load' });
+    if (format === 'screenshot') {
+      return {
+        data: await scratchPage.screenshot({ type: 'png', fullPage: true }),
+        extension: 'png',
+        mimeType: 'image/png',
+      };
+    }
+    if (format === 'pdf') {
+      return {
+        data: await scratchPage.pdf({
+          printBackground: true,
+          preferCSSPageSize: true,
+        }),
+        extension: 'pdf',
+        mimeType: 'application/pdf',
+      };
+    }
+    throw new Error(`Unsupported share format: ${format}`);
+  } finally {
+    await scratchPage.close?.().catch?.(() => {});
+  }
+}
+export async function writeArtifactFile(artifact, deps = {}) {
+  const {
+    artifactDir = DEFAULT_ARTIFACT_DIR,
+    mkdirImpl = mkdir,
+    writeFileImpl = writeFile,
+  } = deps;
+  const filename = toSafeText(artifact?.filename) || 'artifact.txt';
+  const fullPath = path.join(artifactDir, filename);
+  await mkdirImpl(artifactDir, { recursive: true });
+  await writeFileImpl(fullPath, artifact.data, artifact.encoding ? { encoding: artifact.encoding } : undefined);
+  return {
+    path: fullPath,
+    bytes: Buffer.isBuffer(artifact.data)
+      ? artifact.data.length
+      : Buffer.byteLength(String(artifact.data), artifact.encoding === 'utf8' ? 'utf8' : undefined),
+    mimeType: artifact.mimeType ?? null,
+  };
+}

package/src/server/state.js ADDED Viewed

@@ -0,0 +1,132 @@
+import { probe, listTools } from '../layer1-bridge/webmcp.js';
+import { buildHintMap } from '../layer2-perception/hints.js';
+import { createHandoffState } from '../grasp/handoff/state.js';
+import { createPageGraspState, applySnapshotToPageGraspState } from '../grasp/page/state.js';
+import { capturePageSnapshot } from '../grasp/page/capture.js';
+const TRANSIENT_CONTEXT_ERRORS = [
+  'Execution context was destroyed',
+  'Cannot find context with specified id',
+];
+function isTransientExecutionContextError(error) {
+  const message = error?.message ?? '';
+  return TRANSIENT_CONTEXT_ERRORS.some((pattern) => message.includes(pattern));
+}
+async function sleep(ms) {
+  await new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function retryTransientPageStep(step, { attempts = 3, delayMs = 120 } = {}) {
+  let lastError = null;
+  for (let i = 0; i < attempts; i += 1) {
+    try {
+      return await step();
+    } catch (error) {
+      lastError = error;
+      if (!isTransientExecutionContextError(error) || i === attempts - 1) {
+        throw error;
+      }
+      await sleep(delayMs * (i + 1));
+    }
+  }
+  throw lastError;
+}
+export function isSafeModeEnabled() {
+  return process.env.GRASP_SAFE_MODE !== 'false';
+}
+export function createServerState() {
+  return {
+    webmcp: null,
+    hintMap: [],
+    lastUrl: null,
+    targetSession: null,
+    activeTaskId: null,
+    hintRegistry: new Map(),
+    hintCounters: { B: 0, I: 0, L: 0, S: 0 },
+    safeMode: isSafeModeEnabled(),
+    pageState: createPageGraspState(),
+    handoff: createHandoffState(),
+    runtimeTruth: null,
+    runtimeConfirmation: null,
+    verificationContext: null,
+    lastRouteTrace: null,
+    taskFrames: new Map(),
+  };
+}
+export function getActiveTaskFrame(state) {
+  const taskId = state?.activeTaskId ?? state?.taskId ?? null;
+  if (!taskId) return null;
+  return state?.taskFrames?.get(taskId) ?? null;
+}
+export async function syncPageState(page, state, { force = false } = {}) {
+  const url = page.url();
+  const snapshotData = await capturePageSnapshot(page);
+  const snapshotHash = `${url}|${snapshotData.nodes}|${snapshotData.bodyText}`;
+  const prevPageState = state.pageState ?? createPageGraspState();
+  const nextPageState = applySnapshotToPageGraspState(prevPageState, {
+    url,
+    snapshotHash,
+    title: snapshotData.title,
+    bodyText: snapshotData.bodyText,
+    nodes: snapshotData.nodes,
+    forms: snapshotData.forms,
+    navs: snapshotData.navs,
+    headings: snapshotData.headings,
+  });
+  const urlChanged = prevPageState.lastUrl !== url;
+  const domRevisionChanged = prevPageState.domRevision !== nextPageState.domRevision;
+  state.pageState = nextPageState;
+  state.lastUrl = nextPageState.lastUrl;
+  const activeTaskFrame = getActiveTaskFrame(state);
+  if (activeTaskFrame) {
+    activeTaskFrame.lastUrl = nextPageState.lastUrl;
+  }
+  const needsRefresh = force || state.webmcp === null || urlChanged || domRevisionChanged;
+  if (!needsRefresh) return state;
+  if (urlChanged) {
+    state.hintRegistry = new Map();
+    state.hintCounters = { B: 0, I: 0, L: 0, S: 0 };
+  }
+  await retryTransientPageStep(async () => {
+    const webmcp = await probe(page);
+    state.lastUrl = url;
+    if (webmcp.available) {
+      const tools = await listTools(page, webmcp);
+      state.webmcp = { ...webmcp, tools };
+      state.hintMap = [];
+      return;
+    }
+    state.webmcp = webmcp;
+    state.hintMap = await buildHintMap(page, state.hintRegistry, state.hintCounters);
+  });
+  return state;
+}
+export function describeMode(state) {
+  if (state.webmcp?.available) {
+    return {
+      mode: 'WebMCP',
+      detail: `WebMCP via ${state.webmcp.source} (${state.webmcp.tools?.length ?? 0} native tools)`,
+      summary: `WebMCP (${state.webmcp.tools?.length ?? 0} native tools)`,
+    };
+  }
+  return {
+    mode: 'CDP',
+    detail: 'CDP (Hint Map + Mouse Events)',
+    summary: 'CDP (Hint Map + Mouse Events)',
+  };
+}

package/src/server/structured-extraction.js ADDED Viewed

@@ -0,0 +1,131 @@
+function normalizeWhitespace(value) {
+  return String(value ?? '').replace(/\s+/g, ' ').trim();
+}
+export function normalizeStructuredLabel(value) {
+  return normalizeWhitespace(value)
+    .replace(/[：:]+$/u, '')
+    .toLowerCase();
+}
+function scoreStructuredCandidate(field, candidate) {
+  if (!field || !candidate) return 0;
+  if (field === candidate) return 4;
+  if (candidate.includes(field)) return 3;
+  if (field.includes(candidate)) return 2;
+  return 0;
+}
+export function matchStructuredFields(fields = [], candidates = []) {
+  const normalizedCandidates = candidates.map((candidate, index) => ({
+    index,
+    label: normalizeWhitespace(candidate?.label),
+    value: normalizeWhitespace(candidate?.value),
+    strategy: candidate?.strategy ?? 'unknown',
+    normalizedLabel: normalizeStructuredLabel(candidate?.label),
+  })).filter((candidate) => candidate.label && candidate.value);
+  const used = new Set();
+  const record = {};
+  const evidence = [];
+  const missing_fields = [];
+  for (const requestedField of fields) {
+    const field = normalizeWhitespace(requestedField);
+    const normalizedField = normalizeStructuredLabel(requestedField);
+    const matches = normalizedCandidates
+      .filter((candidate) => !used.has(candidate.index))
+      .map((candidate) => ({
+        ...candidate,
+        score: scoreStructuredCandidate(normalizedField, candidate.normalizedLabel),
+      }))
+      .filter((candidate) => candidate.score > 0)
+      .sort((left, right) => right.score - left.score || left.label.length - right.label.length);
+    if (matches.length === 0) {
+      missing_fields.push(field);
+      continue;
+    }
+    const best = matches[0];
+    used.add(best.index);
+    record[field] = best.value;
+    evidence.push({
+      field,
+      label: best.label,
+      value: best.value,
+      strategy: best.strategy,
+    });
+  }
+  return {
+    requested_fields: fields.map((field) => normalizeWhitespace(field)).filter(Boolean),
+    record,
+    missing_fields,
+    evidence,
+  };
+}
+export async function extractStructuredContent(page, fields = []) {
+  const candidates = await page.evaluate(() => {
+    function normalizeWhitespace(value) {
+      return String(value ?? '').replace(/\s+/g, ' ').trim();
+    }
+    function pushCandidate(target, label, value, strategy) {
+      const normalizedLabel = normalizeWhitespace(label);
+      const normalizedValue = normalizeWhitespace(value);
+      if (!normalizedLabel || !normalizedValue) return;
+      const key = `${strategy}::${normalizedLabel}::${normalizedValue}`;
+      if (target.seen.has(key)) return;
+      target.seen.add(key);
+      target.items.push({
+        label: normalizedLabel,
+        value: normalizedValue,
+        strategy,
+      });
+    }
+    const target = { items: [], seen: new Set() };
+    for (const term of document.querySelectorAll('dt')) {
+      const detail = term.nextElementSibling;
+      if (detail && detail.tagName?.toLowerCase() === 'dd') {
+        pushCandidate(target, term.textContent, detail.textContent, 'definition_list');
+      }
+    }
+    for (const row of document.querySelectorAll('tr')) {
+      const headers = [...row.querySelectorAll('th')].map((cell) => normalizeWhitespace(cell.textContent)).filter(Boolean);
+      const cells = [...row.querySelectorAll('td')].map((cell) => normalizeWhitespace(cell.textContent)).filter(Boolean);
+      if (headers.length === 1 && cells.length >= 1) {
+        pushCandidate(target, headers[0], cells.join(' '), 'table_row');
+        continue;
+      }
+      if (headers.length === 0 && cells.length === 2) {
+        pushCandidate(target, cells[0], cells[1], 'table_pair');
+      }
+    }
+    const root = document.querySelector('main') || document.querySelector('article') || document.body;
+    const lines = normalizeWhitespace(root?.innerText ?? '')
+      .split('\n')
+      .map((line) => normalizeWhitespace(line))
+      .filter(Boolean);
+    for (const line of lines) {
+      const separator = line.includes('：') ? '：' : line.includes(':') ? ':' : null;
+      if (!separator) continue;
+      const parts = line.split(separator);
+      if (parts.length < 2) continue;
+      const label = parts.shift();
+      const value = parts.join(separator);
+      pushCandidate(target, label, value, 'inline_pair');
+    }
+    return target.items;
+  });
+  return matchStructuredFields(fields, candidates);
+}