@yuzc-001/grasp 0.6.6

package/src/runtime/browser-instance.js

@@ -0,0 +1,65 @@
+const DEFAULT_TIMEOUT = 1500;
+
+export function inferBrowserInstance(versionInfo = {}) {
+  const browser = typeof versionInfo?.Browser === 'string'
+    ? versionInfo.Browser
+    : null;
+  const protocolVersion = typeof versionInfo?.['Protocol-Version'] === 'string'
+    ? versionInfo['Protocol-Version']
+    : null;
+  const normalized = browser?.toLowerCase() ?? '';
+
+  let headless = null;
+  if (normalized.includes('headlesschrome/')) {
+    headless = true;
+  } else if (normalized.includes('chrome/')) {
+    headless = false;
+  }
+
+  const display = headless === true
+    ? 'headless'
+    : headless === false
+      ? 'windowed'
+      : 'unknown';
+
+  return {
+    browser,
+    protocolVersion,
+    headless,
+    display,
+    warning: headless === true
+      ? 'Current endpoint is a headless browser, not a visible local browser window.'
+      : null,
+  };
+}
+
+export function requireVisibleBrowserInstance(instance, contextLabel = 'This check') {
+  if (instance?.headless === false) return null;
+
+  const label = typeof contextLabel === 'string' && contextLabel.trim()
+    ? contextLabel.trim()
+    : 'This check';
+
+  if (instance?.headless === true) {
+    const browser = instance.browser ?? 'unknown browser';
+    return `${label} requires a visible local browser window. Current browser: ${browser}`;
+  }
+
+  return `${label} requires a visible local browser window. Current browser could not be identified.`;
+}
+
+export async function readBrowserInstance(cdpUrl, {
+  fetchImpl = fetch,
+  timeout = DEFAULT_TIMEOUT,
+} = {}) {
+  try {
+    const res = await fetchImpl(`${cdpUrl}/json/version`, {
+      signal: AbortSignal.timeout(timeout),
+    });
+    if (!res.ok) return null;
+    const versionInfo = await res.json();
+    return inferBrowserInstance(versionInfo);
+  } catch {
+    return null;
+  }
+}

package/src/runtime/truth/model.js

@@ -0,0 +1,94 @@
+export function createRuntimeTruth(overrides = {}) {
+  return {
+    browser_process: {
+      state: 'unknown', // unknown | running | stopped
+      pid: null,
+    },
+    cdp: {
+      state: 'unknown', // unknown | connected | disconnected | unreachable
+      url: process.env.CHROME_CDP_URL || 'http://localhost:9222',
+      browserVersion: null,
+      protocolVersion: null,
+    },
+    page: {
+      state: 'unknown', // unknown | available | unavailable
+      title: null,
+      url: null,
+    },
+    server: {
+      state: 'idle', // idle | connecting | connected | disconnected | error
+      lastError: null,
+      retryCount: 0,
+      connectedAt: null,
+      lastAttemptAt: null,
+    },
+    profile: {
+      state: 'unknown',
+      path: null,
+    },
+    updatedAt: Date.now(),
+    ...overrides,
+  };
+}
+
+export function mergeRuntimeTruth(base, patch = {}) {
+  return {
+    ...base,
+    ...patch,
+    browser_process: { ...(base.browser_process ?? {}), ...(patch.browser_process ?? {}) },
+    cdp: { ...(base.cdp ?? {}), ...(patch.cdp ?? {}) },
+    page: { ...(base.page ?? {}), ...(patch.page ?? {}) },
+    server: { ...(base.server ?? {}), ...(patch.server ?? {}) },
+    profile: { ...(base.profile ?? {}), ...(patch.profile ?? {}) },
+    updatedAt: patch.updatedAt ?? Date.now(),
+  };
+}
+
+export function legacyRuntimeStatusToTruth(snapshot) {
+  if (!snapshot) return createRuntimeTruth();
+
+  const serverState = snapshot.state === 'CDP_UNREACHABLE'
+    ? 'error'
+    : (snapshot.state ?? 'unknown');
+  const cdpState = snapshot.state === 'connected'
+    ? 'connected'
+    : snapshot.state === 'CDP_UNREACHABLE'
+      ? 'unreachable'
+      : 'disconnected';
+
+  return createRuntimeTruth({
+    cdp: {
+      state: cdpState,
+      url: snapshot.cdpUrl ?? (process.env.CHROME_CDP_URL || 'http://localhost:9222'),
+      browserVersion: null,
+      protocolVersion: null,
+    },
+    server: {
+      state: serverState,
+      lastError: snapshot.lastError ?? null,
+      retryCount: snapshot.retryCount ?? 0,
+      connectedAt: snapshot.connectedAt ?? null,
+      lastAttemptAt: snapshot.lastAttemptAt ?? null,
+    },
+    updatedAt: snapshot.updatedAt ?? Date.now(),
+  });
+}
+
+export function truthToLegacyRuntimeStatus(truth) {
+  const cdpState = truth?.cdp?.state;
+  let state = 'idle';
+  if (cdpState === 'connected') state = 'connected';
+  else if (cdpState === 'unreachable') state = 'CDP_UNREACHABLE';
+  else if (truth?.server?.state) state = truth.server.state;
+
+  return {
+    state,
+    retryCount: truth?.server?.retryCount ?? 0,
+    lastError: truth?.server?.lastError ?? null,
+    lastAttemptAt: truth?.server?.lastAttemptAt ?? null,
+    connectedAt: truth?.server?.connectedAt ?? null,
+    cdpUrl: truth?.cdp?.url ?? (process.env.CHROME_CDP_URL || 'http://localhost:9222'),
+    safeMode: process.env.GRASP_SAFE_MODE !== 'false',
+    updatedAt: truth?.updatedAt ?? Date.now(),
+  };
+}

package/src/runtime/truth/snapshot.js

@@ -0,0 +1,51 @@
+import { mkdir, readFile, writeFile } from 'fs/promises';
+import { dirname, join } from 'path';
+import { homedir } from 'os';
+import {
+  createRuntimeTruth,
+  legacyRuntimeStatusToTruth,
+  mergeRuntimeTruth,
+  truthToLegacyRuntimeStatus,
+} from './model.js';
+
+export const RUNTIME_STATUS_PATH =
+  process.env.GRASP_RUNTIME_STATUS_PATH ??
+  join(homedir(), '.grasp', 'runtime-status.json');
+
+async function ensureDir() {
+  await mkdir(dirname(RUNTIME_STATUS_PATH), { recursive: true });
+}
+
+export async function writeRuntimeTruth(snapshot) {
+  try {
+    await ensureDir();
+    const truth = mergeRuntimeTruth(createRuntimeTruth(), snapshot);
+    await writeFile(RUNTIME_STATUS_PATH, JSON.stringify(truth, null, 2) + '\n', 'utf8');
+  } catch {
+    // best effort
+  }
+}
+
+export async function readRuntimeTruth() {
+  try {
+    const raw = await readFile(RUNTIME_STATUS_PATH, 'utf8');
+    const parsed = JSON.parse(raw);
+
+    if (parsed?.browser_process || parsed?.cdp || parsed?.server || parsed?.page || parsed?.profile) {
+      return mergeRuntimeTruth(createRuntimeTruth(), parsed);
+    }
+
+    return legacyRuntimeStatusToTruth(parsed);
+  } catch {
+    return createRuntimeTruth();
+  }
+}
+
+export async function writeRuntimeStatus(snapshot) {
+  return writeRuntimeTruth(legacyRuntimeStatusToTruth(snapshot));
+}
+
+export async function readRuntimeStatus() {
+  const truth = await readRuntimeTruth();
+  return truthToLegacyRuntimeStatus(truth);
+}

package/src/server/affordances.js

@@ -0,0 +1,47 @@
+const SEARCH_KEYWORDS = /search|搜索|提问|ask|query/i;
+const INPUT_TYPES = new Set(['searchbox', 'textbox', 'combobox', 'input', 'textarea']);
+
+function isInputLikeHint(hint = {}) {
+  if (INPUT_TYPES.has(hint.type)) return true;
+  if (hint.meta?.contenteditable === true || hint.meta?.contenteditable === 'true') return true;
+  if (hint.meta?.tag === 'input' || hint.meta?.tag === 'textarea') return true;
+  return false;
+}
+
+function gatherHintText(hint) {
+  return [
+    hint.label,
+    hint.meta?.name,
+    hint.meta?.ariaLabel,
+    hint.meta?.placeholder,
+  ]
+    .filter(Boolean)
+    .join(' ');
+}
+
+function scoreSearchInput(hint) {
+  if (!isInputLikeHint(hint)) return 0;
+  let score = 0;
+  if (isInputLikeHint(hint)) score += 5;
+  if (SEARCH_KEYWORDS.test(hint.label ?? '')) score += 5;
+  if (SEARCH_KEYWORDS.test(gatherHintText(hint))) score += 3;
+  return score;
+}
+
+export function rankAffordances(snapshot = {}) {
+  const hints = (snapshot.hints ?? []).map((hint) => ({ ...hint }));
+  const scored = hints.map((hint) => ({ ...hint, score: scoreSearchInput(hint) }));
+
+  const search_input = scored
+    .filter((hint) => hint.score > 0)
+    .sort((a, b) => {
+      if (b.score !== a.score) return b.score - a.score;
+      return (a.label ?? '').localeCompare(b.label ?? '');
+    });
+
+  const command_button = scored
+    .filter((hint) => hint.type === 'button')
+    .sort((a, b) => (a.label ?? '').localeCompare(b.label ?? ''));
+
+  return { search_input, command_button };
+}

package/src/server/audit.js

@@ -0,0 +1,122 @@
+import { mkdir, appendFile, readFile } from 'fs/promises';
+import { dirname, join } from 'path';
+import { homedir } from 'os';
+
+const LOG_DIR = join(homedir(), '.grasp');
+const LOG_PATH = join(LOG_DIR, 'audit.log');
+
+function getAuditLogPath() {
+  return process.env.GRASP_AUDIT_LOG_PATH || LOG_PATH;
+}
+
+function parseAuditLine(line) {
+  const match = /^\[(.+?)\]\s+(\S+)\s+(.*)$/.exec(String(line ?? ''));
+  if (!match) return null;
+
+  const [, timestamp, action, remainder] = match;
+  let detail = remainder.trim();
+  let meta = null;
+  const markerIndex = detail.lastIndexOf(' :: ');
+
+  if (markerIndex !== -1) {
+    const maybeJson = detail.slice(markerIndex + 4);
+    try {
+      meta = JSON.parse(maybeJson);
+      detail = detail.slice(0, markerIndex).trim();
+    } catch {
+      meta = null;
+    }
+  }
+
+  return {
+    timestamp,
+    action,
+    detail,
+    meta,
+  };
+}
+
+/**
+ * Append one audit entry. Fire-and-forget — failures are silently ignored.
+ * @param {string} action  e.g. 'click', 'navigate', 'type'
+ * @param {string} detail  e.g. '[B1] "发送"'
+ * @param {object|null} meta Optional metadata
+ * @param {object|null} state Optional server state for task-awareness
+ */
+export async function audit(action, detail, meta = null, state = null) {
+  const taskId = state?.activeTaskId ?? null;
+  
+  if (state && taskId) {
+    const frame = state.taskFrames?.get(taskId);
+    if (frame) {
+      frame.history = frame.history || [];
+      frame.history.push({
+        timestamp: new Date().toISOString(),
+        action,
+        detail,
+        meta
+      });
+      if (frame.history.length > 0) {
+        // Cap history to prevent memory bloat
+        if (frame.history.length > 100) {
+          frame.history.shift();
+        }
+      }
+    }
+  }
+
+  try {
+    const taskMarker = taskId ? ` <${taskId}>` : '';
+    const logPath = getAuditLogPath();
+    await mkdir(dirname(logPath), { recursive: true });
+    const ts = new Date().toISOString().replace('T', ' ').slice(0, 19);
+    const suffix = meta ? ` :: ${JSON.stringify(meta)}` : '';
+    const line = `[${ts}] ${action.padEnd(14)}${taskMarker} ${detail}${suffix}\n`;
+    await appendFile(logPath, line, 'utf8');
+  } catch {
+    // Logging failures must never affect the main tool flow.
+  }
+}
+
+export async function auditRouteDecision(trace, state = null) {
+  const intent = trace?.intent ?? 'unknown';
+  const mode = trace?.selected_mode ?? 'unknown';
+  const url = trace?.url ?? 'unknown';
+  await audit('route_decision', `${intent} -> ${mode} @ ${url}`, trace, state);
+}
+
+/**
+ * Read the last N lines from the audit log.
+ * @param {number} [n=50]
+ * @returns {Promise<string[]>}
+ */
+export async function readLogs(n = 50) {
+  try {
+    const content = await readFile(getAuditLogPath(), 'utf8');
+    const lines = content.split('\n').filter(Boolean);
+    return lines.slice(-n);
+  } catch {
+    return [];
+  }
+}
+
+export async function readLatestRouteDecision() {
+  try {
+    const content = await readFile(getAuditLogPath(), 'utf8');
+    const lines = content.split('\n').filter(Boolean).reverse();
+
+    for (const line of lines) {
+      const entry = parseAuditLine(line);
+      if (entry?.action !== 'route_decision' || !entry.meta) continue;
+      return {
+        timestamp: entry.timestamp,
+        detail: entry.detail,
+        ...entry.meta,
+      };
+    }
+
+    return null;
+  } catch {
+    return null;
+  }
+}

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

@@ -0,0 +1,164 @@
+export function detectBossSurface(url, signals = {}) {
+  const currentUrl = String(url ?? '');
+
+  if (!currentUrl.includes('zhipin.com')) {
+    return { surface: 'non_boss' };
+  }
+
+  if (signals.hasComposer || signals.hasSendButton || currentUrl.includes('/web/geek/chat')) {
+    return { surface: 'chat' };
+  }
+
+  if (signals.hasChatEntry || currentUrl.includes('job_detail')) {
+    return { surface: 'detail' };
+  }
+
+  if (signals.hasSearchLinks || currentUrl.includes('/web/geek/jobs')) {
+    return { surface: 'search' };
+  }
+
+  return { surface: 'non_boss' };
+}
+
+export async function readBossSearchSurface(page) {
+  const currentUrl = page.url();
+  const jobs = await page.evaluate(() => {
+    return Array.from(document.querySelectorAll('a[href*="job_detail"]'))
+      .map((node) => {
+        const title = String(node.innerText || node.textContent || '').replace(/\s+/g, ' ').trim();
+        const href = node.getAttribute?.('href') ?? node.href ?? '';
+        return title ? { title, href } : null;
+      })
+      .filter(Boolean);
+  });
+  return { currentUrl, jobs };
+}
+
+export async function readBossJobDetailSurface(page) {
+  const currentUrl = page.url();
+  const result = await page.evaluate(() => {
+    const title = String(document.title || '').replace(/\s+/g, ' ').trim();
+    const chatNode = document.querySelector('[data-url*="/wapi/zpgeek/friend/add.json"]');
+
+    return {
+      title,
+      chatEntry: chatNode ? {
+        text: String(chatNode.innerText || chatNode.textContent || '').replace(/\s+/g, ' ').trim(),
+        redirectUrl: chatNode.getAttribute?.('redirect-url')
+          ?? chatNode.getAttribute?.('data-url')
+          ?? null,
+      } : null,
+    };
+  });
+  return { currentUrl, ...result };
+}
+
+export async function readBossChatSurface(page) {
+  const currentUrl = page.url();
+  const result = await page.evaluate(() => {
+    const composer = document.querySelector('.chat-input[contenteditable="true"]');
+    const sendButton = document.querySelector('button.btn-send');
+    const historyNodes = Array.from(document.querySelectorAll('.item-myself, .item-friend, .message-item'))
+      .slice(-3)
+      .map((node) => String(node.innerText || node.textContent || '').replace(/\s+/g, ' ').trim())
+      .filter(Boolean);
+
+    return {
+      composerText: String(composer?.innerText || composer?.textContent || '').replace(/\s+/g, ' ').trim(),
+      sendButtonText: String(sendButton?.innerText || sendButton?.textContent || '').replace(/\s+/g, ' ').trim(),
+      historySignal: historyNodes.join('\n'),
+    };
+  });
+  return { currentUrl, ...result };
+}
+
+function buildFastPathContent({ surface, title, url, text }) {
+  const normalizedTitle = String(title ?? '').trim() || 'BOSS';
+  const normalizedText = String(text ?? '').trim() || normalizedTitle;
+  return {
+    surface,
+    title: normalizedTitle,
+    url,
+    mainText: normalizedText,
+  };
+}
+
+export const bossFastPathAdapter = {
+  id: 'boss',
+  matches(url) {
+    try {
+      const { hostname } = new URL(String(url ?? ''));
+      return hostname === 'bosszhipin.com'
+        || hostname === 'zhipin.com'
+        || hostname.endsWith('.bosszhipin.com')
+        || hostname.endsWith('.zhipin.com');
+    } catch {
+      return false;
+    }
+  },
+  async read(page) {
+    const currentUrl = page.url();
+    if (!this.matches(currentUrl)) {
+      return null;
+    }
+
+    const [title, pageInfo] = await Promise.all([
+      page.title(),
+      page.evaluate(() => ({
+        hasComposer: Boolean(document.querySelector('.chat-input[contenteditable="true"]')),
+        hasSendButton: Boolean(document.querySelector('button.btn-send')),
+        hasChatEntry: Boolean(document.querySelector('[data-url*="/wapi/zpgeek/friend/add.json"]')),
+        hasSearchLinks: Boolean(document.querySelector('a[href*="job_detail"]')),
+      })),
+    ]);
+
+    const { surface } = detectBossSurface(currentUrl, {
+      title,
+      ...pageInfo,
+    });
+
+    if (surface === 'non_boss') {
+      return null;
+    }
+
+    if (surface === 'search') {
+      const result = await readBossSearchSurface(page);
+      return buildFastPathContent({
+        surface,
+        title,
+        url: result.currentUrl,
+        text: (result.jobs ?? []).map((job) => job.title).join('\n'),
+      });
+    }
+
+    if (surface === 'detail') {
+      const result = await readBossJobDetailSurface(page);
+      return buildFastPathContent({
+        surface,
+        title: result.title || title,
+        url: result.currentUrl,
+        text: [
+          result.title,
+          result.chatEntry?.text,
+          result.chatEntry?.redirectUrl,
+        ].filter(Boolean).join('\n'),
+      });
+    }
+
+    if (surface === 'chat') {
+      const result = await readBossChatSurface(page);
+      return buildFastPathContent({
+        surface,
+        title,
+        url: result.currentUrl,
+        text: [
+          result.composerText,
+          result.sendButtonText,
+          result.historySignal,
+        ].filter(Boolean).join('\n'),
+      });
+    }
+
+    return null;
+  },
+};

package/src/server/boundary-guard.js

@@ -0,0 +1,53 @@
+import { buildGatewayResponse } from './gateway-response.js';
+import { BOUNDARY_MISMATCH } from './error-codes.js';
+import {
+  buildBoundaryContinuation,
+  buildBoundaryMismatchLines,
+  inferSurfaceBoundaryKey,
+} from './route-boundary.js';
+
+function getBoundaryStatus(status, currentBoundary) {
+  if (status === 'handoff_required' || status === 'gated' || status === 'warmup') {
+    return status;
+  }
+
+  if (currentBoundary === 'session_warmup') {
+    return 'warmup';
+  }
+
+  return 'blocked';
+}
+
+export function guardExpectedBoundary({
+  toolName,
+  expectedBoundary,
+  status,
+  page,
+  handoffState = 'idle',
+} = {}) {
+  const currentBoundary = inferSurfaceBoundaryKey({ page });
+  if (!currentBoundary || currentBoundary === expectedBoundary) {
+    return null;
+  }
+
+  const continuation = buildBoundaryContinuation(currentBoundary, handoffState);
+  return buildGatewayResponse({
+    status: getBoundaryStatus(status, currentBoundary),
+    page,
+    result: {
+      status: 'blocked',
+      reason: 'boundary_mismatch',
+      expected_boundary: expectedBoundary,
+      current_boundary: currentBoundary,
+      next_step: continuation.suggested_next_action,
+    },
+    continuation,
+    error_code: BOUNDARY_MISMATCH,
+    message: buildBoundaryMismatchLines({
+      toolName,
+      expectedBoundary,
+      currentBoundary,
+      nextStep: continuation.suggested_next_action,
+    }),
+  });
+}

package/src/server/content.js

@@ -0,0 +1,97 @@
+const DEFAULT_STABLE_CHECKS = 3;
+const DEFAULT_INTERVAL = 200;
+const DEFAULT_TIMEOUT = 5000;
+
+function normalizeText(value) {
+  return String(value ?? '').trim();
+}
+
+async function defaultSnapshot(page) {
+  return page.evaluate(() => {
+    const safeText = (el) => (el?.innerText ?? '').trim();
+    const main = document.querySelector('main') || document.querySelector('article');
+    const mainText = safeText(main);
+    const bodyText = safeText(document.body);
+    return {
+      title: document.title ?? '',
+      mainText,
+      bodyText,
+      readyState: document.readyState,
+    };
+  });
+}
+
+export async function extractMainContent(page) {
+  const { title, mainText, bodyText } = await defaultSnapshot(page);
+  const text = (mainText && mainText.length > 0) ? mainText : bodyText;
+  return {
+    title,
+    text: (text ?? '').trim(),
+  };
+}
+
+export function summarizeExtractedText(text) {
+  const normalized = normalizeText(text).replace(/\s+/g, ' ');
+  if (!normalized) {
+    return '';
+  }
+
+  const sentenceMatch = normalized.match(/^(.+?)[.!?](?:\s|$)/);
+  if (sentenceMatch) {
+    return sentenceMatch[1].trim();
+  }
+
+  return normalized.length > 120 ? `${normalized.slice(0, 117).trimEnd()}...` : normalized;
+}
+
+export function toMarkdownDocument({ title, text }) {
+  return `# ${title || 'Untitled'}\n\n${text}`.trim();
+}
+
+export async function waitUntilStable(page, options = {}) {
+  const {
+    getSnapshot,
+    stableChecks = DEFAULT_STABLE_CHECKS,
+    interval = DEFAULT_INTERVAL,
+    timeout = DEFAULT_TIMEOUT,
+  } = options;
+
+  const snapshotter = typeof getSnapshot === 'function'
+    ? () => getSnapshot(page)
+    : () => defaultSnapshot(page);
+
+  const start = Date.now();
+  const history = [];
+  let lastSnapshot;
+
+  while (Date.now() - start < timeout) {
+    const snapshot = await snapshotter();
+    history.push(snapshot);
+    lastSnapshot = snapshot;
+
+    if (history.length >= stableChecks) {
+      const recent = history.slice(-stableChecks);
+      const normalized = recent.map((item) => JSON.stringify(item));
+      const first = normalized[0];
+      if (normalized.every((value) => value === first)) {
+        return {
+          stable: true,
+          attempts: history.length,
+          snapshot: recent[0],
+        };
+      }
+    }
+
+    if (interval > 0) {
+      await new Promise((resolve) => setTimeout(resolve, interval));
+    } else {
+      await new Promise((resolve) => setTimeout(resolve, 0));
+    }
+  }
+
+  return {
+    stable: false,
+    attempts: history.length,
+    snapshot: lastSnapshot,
+  };
+}