@yuzc-001/grasp 0.6.6

package/src/server/continuity.js

@@ -0,0 +1,256 @@
+import { deriveWorkspaceHintItems } from './workspace-tasks.js';
+
+export function buildCheckpointHandoffSuggestion(pageState = {}, pageUrl = '') {
+  const checkpointKind = pageState.checkpointKind ?? 'unknown';
+  const role = pageState.currentRole ?? 'unknown';
+  const reason = checkpointKind === 'waiting_room'
+    ? 'checkpoint_waiting_room'
+    : checkpointKind === 'challenge'
+      ? 'checkpoint_challenge'
+      : checkpointKind === 'verification'
+        ? 'checkpoint_verification'
+        : 'checkpoint_required';
+
+  const note = `Checkpoint detected (${checkpointKind}) at ${pageUrl || 'current page'}; human presence may be required before continuation can resume.`;
+
+  return {
+    reason,
+    note,
+    expected_url_contains: (() => {
+      try {
+        const url = new URL(pageUrl);
+        return url.hostname;
+      } catch {
+        return null;
+      }
+    })(),
+    expected_page_role: role === 'checkpoint' ? null : role,
+    expected_selector: null,
+    continuation_goal: 'resume after checkpoint clearance',
+    expected_hint_label: null,
+    checkpoint_kind: checkpointKind,
+    checkpoint_signals: pageState.checkpointSignals ?? [],
+    suggested_next_action: pageState.suggestedNextAction ?? 'handoff_required',
+  };
+}
+
+export function buildSessionTrustPreflight(targetUrl, pageState = {}, handoff = {}) {
+  let hostname = null;
+  let currentHostname = null;
+  try {
+    hostname = new URL(targetUrl).hostname.toLowerCase();
+  } catch {}
+  try {
+    currentHostname = pageState?.lastUrl ? new URL(pageState.lastUrl).hostname.toLowerCase() : null;
+  } catch {}
+
+  const sameTargetContext = !!(hostname && currentHostname && hostname === currentHostname);
+
+  const highRiskHost = hostname && (
+    hostname.includes('chatgpt.com') ||
+    hostname.includes('openai.com') ||
+    hostname.includes('github.com')
+  );
+
+  const checkpointActive = sameTargetContext && (pageState.currentRole === 'checkpoint' || pageState.riskGateDetected === true);
+  const priorHandoffForSameHost = !!(handoff.expected_url_contains && hostname && handoff.expected_url_contains.includes(hostname));
+
+  let sessionTrust = 'medium';
+  let recommendedEntryStrategy = 'direct';
+  const trustSignals = [];
+
+  if (highRiskHost) trustSignals.push('high_risk_host');
+  if (priorHandoffForSameHost) trustSignals.push('prior_handoff_context_for_host');
+  if (sameTargetContext) {
+    trustSignals.push('same_target_context');
+  }
+  if (checkpointActive) trustSignals.push('active_checkpoint_detected');
+
+  if (highRiskHost && checkpointActive) {
+    sessionTrust = 'low';
+    recommendedEntryStrategy = 'handoff_or_preheat';
+  } else if (highRiskHost && priorHandoffForSameHost) {
+    sessionTrust = 'medium';
+    recommendedEntryStrategy = 'resume_existing_session';
+  } else if (highRiskHost) {
+    sessionTrust = 'low';
+    recommendedEntryStrategy = 'preheat_before_direct_entry';
+  }
+
+  return {
+    target_url: targetUrl,
+    hostname,
+    current_hostname: currentHostname,
+    same_target_context: sameTargetContext,
+    session_trust: sessionTrust,
+    recommended_entry_strategy: recommendedEntryStrategy,
+    trust_signals: trustSignals,
+    checkpoint_active: checkpointActive,
+  };
+}
+
+export async function assessResumeContinuation(page, state, anchors = {}) {
+  const {
+    expected_url_contains = null,
+    expected_page_role = null,
+    expected_selector = null,
+    continuation_goal = null,
+    expected_hint_label = null,
+  } = anchors;
+
+  const checks = [];
+  const currentUrl = page?.url?.() ?? '';
+  const currentRole = state?.pageState?.currentRole ?? 'unknown';
+
+  if (expected_url_contains) {
+    checks.push({ kind: 'url_contains', expected: expected_url_contains, ok: currentUrl.includes(expected_url_contains), actual: currentUrl });
+  }
+
+  if (expected_page_role) {
+    checks.push({ kind: 'page_role', expected: expected_page_role, ok: currentRole === expected_page_role, actual: currentRole });
+  }
+
+  if (expected_selector) {
+    let found = false;
+    try {
+      found = await page.evaluate((selector) => Boolean(document.querySelector(selector)), expected_selector);
+    } catch {}
+    checks.push({ kind: 'selector_present', expected: expected_selector, ok: found, actual: found });
+  }
+
+  if (expected_hint_label) {
+    const hintMatch = (state?.hintMap ?? []).find((hint) =>
+      String(hint?.label ?? '').toLowerCase().includes(String(expected_hint_label).toLowerCase())
+    );
+    checks.push({ kind: 'hint_label_present', expected: expected_hint_label, ok: Boolean(hintMatch), actual: hintMatch?.label ?? null });
+  }
+
+  const requiredChecks = checks.length;
+  const passedChecks = checks.filter((check) => check.ok).length;
+  const taskContinuationOk = requiredChecks === 0 ? null : passedChecks === requiredChecks;
+  const continuationReady = taskContinuationOk === true && (!expected_hint_label || checks.some((check) => check.kind === 'hint_label_present' && check.ok));
+  const suggestedNextAction = continuationReady
+    ? expected_hint_label
+      ? `use_hint_matching:${expected_hint_label}`
+      : continuation_goal
+        ? `continue_goal:${continuation_goal}`
+        : 'continue_task'
+    : taskContinuationOk === false
+      ? 'do_not_continue'
+      : 'needs_confirmation';
+
+  return {
+    required_checks: requiredChecks,
+    passed_checks: passedChecks,
+    task_continuation_ok: taskContinuationOk,
+    continuation_ready: continuationReady,
+    continuation_goal,
+    suggested_next_action: suggestedNextAction,
+    checks,
+  };
+}
+
+export async function assessGatewayContinuation(page, state) {
+  const handoffState = state?.handoff?.state ?? 'idle';
+  const pageState = state?.pageState ?? {};
+  const gatedByPage = pageState.currentRole === 'checkpoint' || pageState.riskGateDetected === true;
+  const anchors = {
+    expected_url_contains: state?.handoff?.expected_url_contains ?? null,
+    expected_page_role: state?.handoff?.expected_page_role ?? null,
+    expected_selector: state?.handoff?.expected_selector ?? null,
+    continuation_goal: state?.handoff?.continuation_goal ?? null,
+    expected_hint_label: state?.handoff?.expected_hint_label ?? null,
+  };
+
+  if (handoffState === 'handoff_required' || handoffState === 'handoff_in_progress' || handoffState === 'awaiting_reacquisition') {
+    return {
+      status: 'handoff_required',
+      continuation: {
+        can_continue: false,
+        suggested_next_action: 'request_handoff',
+        handoff_state: handoffState,
+      },
+    };
+  }
+
+  if (gatedByPage) {
+    return {
+      status: 'gated',
+      continuation: {
+        can_continue: false,
+        suggested_next_action: 'request_handoff',
+        handoff_state: handoffState,
+      },
+    };
+  }
+
+  const continuation = await assessResumeContinuation(page, state, anchors);
+  const workspaceHintItems = deriveWorkspaceHintItems(state?.hintMap ?? []);
+  const workspaceLike = pageState.currentRole === 'workspace'
+    || pageState.currentRole === 'navigation-heavy'
+    || pageState.workspaceSurface === 'list'
+    || (pageState.workspaceSignals ?? []).includes('workspace_navigation')
+    || workspaceHintItems.length > 0;
+  const suggestedDirectAction = workspaceLike
+    ? 'workspace_inspect'
+    : pageState.currentRole === 'form' || pageState.currentRole === 'auth'
+      ? 'form_inspect'
+      : continuation.suggested_next_action === 'needs_confirmation'
+        ? 'extract'
+      : continuation.suggested_next_action;
+
+  if (handoffState === 'resumed_verified' || handoffState === 'resumed_unverified') {
+    if (continuation.task_continuation_ok === false) {
+      return {
+        status: 'failed',
+        continuation: {
+          ...continuation,
+          can_continue: false,
+          handoff_state: handoffState,
+        },
+      };
+    }
+
+    if (continuation.continuation_ready) {
+      return {
+        status: 'resumed',
+        continuation: {
+          ...continuation,
+          suggested_next_action: suggestedDirectAction,
+          can_continue: true,
+          handoff_state: handoffState,
+        },
+      };
+    }
+
+    return {
+      status: 'failed',
+      continuation: {
+        ...continuation,
+        can_continue: false,
+        handoff_state: handoffState,
+      },
+    };
+  }
+
+  if (continuation.task_continuation_ok === false) {
+    return {
+      status: 'failed',
+      continuation: {
+        ...continuation,
+        can_continue: false,
+        handoff_state: handoffState,
+      },
+    };
+  }
+
+  return {
+    status: 'direct',
+    continuation: {
+      ...continuation,
+      suggested_next_action: suggestedDirectAction,
+      can_continue: true,
+      handoff_state: handoffState,
+    },
+  };
+}

package/src/server/engine-selection.js

@@ -0,0 +1,29 @@
+function normalizeHostname(url) {
+  try {
+    return new URL(String(url ?? '')).hostname.toLowerCase();
+  } catch {
+    return '';
+  }
+}
+
+function isRuntimeHost(hostname) {
+  return hostname === 'bosszhipin.com'
+    || hostname === 'zhipin.com'
+    || hostname.endsWith('.bosszhipin.com')
+    || hostname.endsWith('.zhipin.com')
+    || hostname === 'mp.weixin.qq.com'
+    || hostname.endsWith('.mp.weixin.qq.com')
+    || hostname === 'xiaohongshu.com'
+    || hostname === 'www.xiaohongshu.com'
+    || hostname.endsWith('.xiaohongshu.com')
+    || hostname === 'xhslink.com'
+    || hostname.endsWith('.xhslink.com');
+}
+
+export function selectEngine({ tool, url } = {}) {
+  const hostname = normalizeHostname(url);
+  return {
+    tool: tool ?? 'extract',
+    engine: isRuntimeHost(hostname) ? 'runtime' : 'data',
+  };
+}

package/src/server/entry-orchestrator.js

@@ -0,0 +1,115 @@
+function normalizeUrl(url) {
+  try {
+    const parsed = new URL(url);
+    if (parsed.pathname !== '/' && parsed.pathname.endsWith('/')) {
+      parsed.pathname = parsed.pathname.slice(0, -1);
+    }
+    parsed.hash = '';
+    return parsed.toString();
+  } catch {
+    return url ?? null;
+  }
+}
+
+async function readPageAvailability(page) {
+  if (!page) {
+    return { available: false, finalUrl: null };
+  }
+
+  if (page.isClosed?.() === true) {
+    return { available: false, finalUrl: null };
+  }
+
+  const finalUrl = page.url?.() ?? null;
+  if (!finalUrl) {
+    return { available: false, finalUrl: null };
+  }
+
+  try {
+    if (typeof page.evaluate === 'function') {
+      await page.evaluate(() => document.location.href);
+    }
+    return { available: true, finalUrl };
+  } catch {
+    return { available: false, finalUrl };
+  }
+}
+
+export function createEntryOrchestrator({
+  directGoto,
+  trustedContextOpen,
+} = {}) {
+  const runStrategy = async (strategy, targetUrl, state) => {
+    if (strategy === 'direct_goto') {
+      return directGoto(targetUrl, { state });
+    }
+    if (strategy === 'trusted_context_open') {
+      return trustedContextOpen(targetUrl, { state });
+    }
+    throw new Error(`Unknown entry strategy: ${strategy}`);
+  };
+
+  return {
+    async run({ targetUrl, strategies = [], state = null }) {
+      const attempts = [];
+      let lastAttempt = {
+        page: null,
+        finalUrl: null,
+        strategy: strategies[0] ?? null,
+      };
+
+      for (const strategy of strategies) {
+        lastAttempt = {
+          page: null,
+          finalUrl: null,
+          strategy,
+        };
+
+        try {
+          const page = await runStrategy(strategy, targetUrl, state);
+          const { available, finalUrl } = await readPageAvailability(page);
+          const verified = normalizeUrl(finalUrl) === normalizeUrl(targetUrl);
+
+          lastAttempt = {
+            page,
+            finalUrl,
+            strategy,
+          };
+
+          attempts.push({
+            strategy,
+            final_url: finalUrl,
+            page_available: available,
+            verified,
+          });
+
+          if (verified) {
+            return {
+              page,
+              entry_method: strategy,
+              final_url: finalUrl,
+              verified: true,
+              evidence: { attempts },
+            };
+          }
+        } catch (error) {
+          attempts.push({
+            strategy,
+            final_url: null,
+            page_available: false,
+            verified: false,
+            error: error.message,
+          });
+        }
+      }
+
+      return {
+        page: lastAttempt.page,
+        entry_method: lastAttempt.strategy,
+        final_url: lastAttempt.finalUrl,
+        verified: false,
+        evidence: { attempts },
+      };
+    },
+  };
+}

package/src/server/error-codes.js

@@ -0,0 +1,7 @@
+export const ACTION_NOT_VERIFIED = 'ACTION_NOT_VERIFIED';
+export const TYPE_FAILED = 'TYPE_FAILED';
+export const NO_EFFECT = 'NO_EFFECT';
+export const LOADING_PENDING = 'LOADING_PENDING';
+export const EXECUTION_FAILED = 'EXECUTION_FAILED';
+export const ROUTE_BLOCKED = 'ROUTE_BLOCKED';
+export const BOUNDARY_MISMATCH = 'BOUNDARY_MISMATCH';

package/src/server/explain-share-card.js

@@ -0,0 +1,113 @@
+const PRETEXT_MODULE_URL = new URL('../../node_modules/@chenglou/pretext/dist/layout.js', import.meta.url).href;
+
+function normalizeText(value, fallback = '') {
+  return String(value ?? fallback).trim();
+}
+
+function fallbackLayout(text, maxWidth, lineHeight) {
+  const normalized = normalizeText(text);
+  if (!normalized) {
+    return { height: lineHeight, lineCount: 1 };
+  }
+
+  const charsPerLine = Math.max(10, Math.floor(maxWidth / 9));
+  const lineCount = Math.max(1, Math.ceil(normalized.length / charsPerLine));
+  return {
+    height: lineCount * lineHeight,
+    lineCount,
+  };
+}
+
+async function defaultCreateScratchPage(page) {
+  const context = page?.context?.();
+  if (!context || typeof context.newPage !== 'function') {
+    throw new Error('Pretext measurement requires a browser page context.');
+  }
+  return context.newPage();
+}
+
+async function measureWithPretext(page, blocks, deps = {}) {
+  const createScratchPage = deps.createScratchPage ?? defaultCreateScratchPage;
+  const scratchPage = await createScratchPage(page);
+
+  try {
+    await scratchPage.setContent('<!doctype html><html><body></body></html>', { waitUntil: 'load' });
+    await scratchPage.addScriptTag({
+      type: 'module',
+      content: `
+        import { prepare, layout } from ${JSON.stringify(PRETEXT_MODULE_URL)};
+        window.__graspPretextMeasure = async (blocks) => {
+          return blocks.map((block) => {
+            const prepared = prepare(block.text, block.font, { whiteSpace: block.whiteSpace ?? 'normal' });
+            const result = layout(prepared, block.maxWidth, block.lineHeight);
+            return {
+              key: block.key,
+              height: result.height,
+              lineCount: result.lineCount,
+            };
+          });
+        };
+      `,
+    });
+
+    return scratchPage.evaluate(async (input) => {
+      return window.__graspPretextMeasure(input);
+    }, blocks);
+  } finally {
+    await scratchPage.close?.().catch?.(() => {});
+  }
+}
+
+export async function buildExplainShareCard(page, projection, options = {}, deps = {}) {
+  const width = Number(options.width ?? 640);
+  const title = normalizeText(projection?.title, 'Untitled');
+  const summary = normalizeText(projection?.summary, projection?.main_text);
+  const bodyExcerpt = normalizeText(projection?.main_text).slice(0, 420);
+  const blocks = [
+    { key: 'title', text: title, font: '600 28px Arial', maxWidth: width, lineHeight: 34 },
+    { key: 'summary', text: summary, font: '16px Arial', maxWidth: width, lineHeight: 24 },
+    { key: 'body', text: bodyExcerpt, font: '14px Arial', maxWidth: width, lineHeight: 22, whiteSpace: 'pre-wrap' },
+  ];
+
+  let engine = 'fallback';
+  let measured = blocks.map((block) => ({
+    key: block.key,
+    ...fallbackLayout(block.text, block.maxWidth, block.lineHeight),
+  }));
+
+  try {
+    const nextMeasured = await measureWithPretext(page, blocks, deps);
+    if (Array.isArray(nextMeasured) && nextMeasured.length === blocks.length) {
+      measured = nextMeasured;
+      engine = 'pretext';
+    }
+  } catch {
+    // fall back to deterministic approximation
+  }
+
+  const byKey = Object.fromEntries(measured.map((item) => [item.key, item]));
+  const estimatedHeight = (byKey.title?.height ?? 0)
+    + (byKey.summary?.height ?? 0)
+    + (byKey.body?.height ?? 0)
+    + 220;
+
+  return {
+    engine,
+    width,
+    estimated_height: estimatedHeight,
+    title_lines: byKey.title?.lineCount ?? 1,
+    summary_lines: byKey.summary?.lineCount ?? 1,
+    body_lines: byKey.body?.lineCount ?? 1,
+    body_excerpt: bodyExcerpt,
+    card_markdown: [
+      `# ${title}`,
+      '',
+      `Source: ${normalizeText(projection?.url, 'unknown')}`,
+      '',
+      `Summary: ${summary}`,
+      '',
+      `Layout engine: ${engine}`,
+      `Estimated height: ${estimatedHeight}px`,
+    ].join('\n'),
+  };
+}

package/src/server/fast-path-router.js

@@ -0,0 +1,134 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { bossFastPathAdapter } from './boss-fast-path.js';
+
+const DEFAULT_ADAPTER_DIR = path.join(os.homedir(), '.grasp', 'site-adapters');
+
+function normalizeEntry(value) {
+  return String(value ?? '').trim();
+}
+
+function parseSkillEntry(source) {
+  const text = String(source ?? '');
+  const frontmatterMatch = text.match(/^---\s*([\s\S]*?)\s*---/);
+  const candidates = [
+    frontmatterMatch?.[1] ?? '',
+    text,
+  ];
+
+  for (const candidate of candidates) {
+    const entryMatch = candidate.match(/^(?:entry|adapter)\s*:\s*(.+)$/m);
+    if (entryMatch) {
+      return normalizeEntry(entryMatch[1]);
+    }
+  }
+
+  return '';
+}
+
+function normalizeAdapter(candidate) {
+  if (!candidate || typeof candidate !== 'object') {
+    return null;
+  }
+
+  const matches = typeof candidate.matches === 'function'
+    ? candidate.matches.bind(candidate)
+    : typeof candidate.match === 'function'
+      ? candidate.match.bind(candidate)
+      : null;
+  const read = typeof candidate.read === 'function'
+    ? candidate.read.bind(candidate)
+    : null;
+
+  if (!matches || !read) {
+    return null;
+  }
+
+  return {
+    id: normalizeEntry(candidate.id) || 'external-adapter',
+    matches,
+    read,
+  };
+}
+
+async function importAdapterModule(modulePath, loader = (target) => import(target)) {
+  const mod = await loader(pathToFileURL(modulePath).href);
+  return normalizeAdapter(mod.default ?? mod.adapter ?? mod);
+}
+
+async function loadAdaptersFromDir(dirPath, deps = {}) {
+  const {
+    readdirImpl = readdir,
+    readFileImpl = readFile,
+    importModule = (target) => import(target),
+  } = deps;
+
+  if (!dirPath || !existsSync(dirPath)) {
+    return [];
+  }
+
+  const entries = await readdirImpl(dirPath, { withFileTypes: true });
+  const adapters = [];
+
+  for (const entry of entries) {
+    if (!entry.isFile()) continue;
+
+    const filePath = path.join(dirPath, entry.name);
+    if (entry.name.endsWith('.js')) {
+      const adapter = await importAdapterModule(filePath, importModule);
+      if (adapter) adapters.push(adapter);
+      continue;
+    }
+
+    if (entry.name.endsWith('.skill')) {
+      const skillSource = await readFileImpl(filePath, 'utf8');
+      const relativeEntry = parseSkillEntry(skillSource);
+      if (!relativeEntry) continue;
+      const targetPath = path.resolve(path.dirname(filePath), relativeEntry);
+      const adapter = await importAdapterModule(targetPath, importModule);
+      if (adapter) adapters.push(adapter);
+    }
+  }
+
+  return adapters;
+}
+
+export async function resolveFastPathAdapters(deps = {}) {
+  const adapterDirs = Array.isArray(deps.adapterDirs)
+    ? deps.adapterDirs
+    : [process.env.GRASP_SITE_ADAPTER_DIR || DEFAULT_ADAPTER_DIR].filter(Boolean);
+  const externalAdapters = [];
+
+  for (const dirPath of adapterDirs) {
+    const loaded = await loadAdaptersFromDir(dirPath, deps);
+    externalAdapters.push(...loaded);
+  }
+
+  return [bossFastPathAdapter, ...externalAdapters];
+}
+
+export async function readFastPath(page, deps = {}) {
+  const adapters = await resolveFastPathAdapters(deps);
+  const currentUrl = page.url();
+
+  for (const adapter of adapters) {
+    if (!adapter.matches(currentUrl)) {
+      continue;
+    }
+
+    const result = await adapter.read(page, { url: currentUrl });
+    if (result) {
+      return result;
+    }
+  }
+
+  return null;
+}
+
+export async function readBossFastPath(page) {
+  return readFastPath(page, { adapterDirs: [] });
+}