@yuzc-001/grasp 0.6.6

package/src/server/surface-prompts.js

@@ -0,0 +1,166 @@
+const BOUNDARY_PROMPT_PACKS = {
+  public_read: {
+    id: 'public_read',
+    instructions: [
+      'Operate as a read-first agent inside the current Grasp runtime boundary.',
+      'Keep the flow on inspect/extract style tools until the runtime evidence shows a different surface.',
+      'Do not mutate the page or jump into form/workspace actions from a readable public page.',
+    ],
+  },
+  live_session: {
+    id: 'live_session',
+    instructions: [
+      'Operate inside the current authenticated browser session instead of replaying from scratch.',
+      'Inspect the live page first and wait for clear evidence before switching into a specialized surface.',
+      'Reuse the current session state and avoid speculative deep actions.',
+    ],
+  },
+  session_warmup: {
+    id: 'session_warmup',
+    instructions: [
+      'Treat this as a trust-warmup path, not a direct action path.',
+      'Preheat the session, then re-enter once the runtime trust improves.',
+      'Avoid blind retries that keep re-triggering the same low-trust entry.',
+    ],
+  },
+  form_runtime: {
+    id: 'form_runtime',
+    instructions: [
+      'Operate as a guarded form agent.',
+      'Inspect first, fill safe text fields conservatively, and keep review-tier controls explicit.',
+      'Submit only through safe_submit with the required confirmation gate.',
+    ],
+  },
+  workspace_runtime: {
+    id: 'workspace_runtime',
+    instructions: [
+      'Operate as a guarded workspace agent on the current live item.',
+      'Keep selection stable, draft before execute, and verify outcome after every execution.',
+      'Never bypass the guarded workspace tools with raw send-like actions.',
+    ],
+  },
+  handoff: {
+    id: 'handoff',
+    instructions: [
+      'Operate as a handoff coordinator rather than a direct actor.',
+      'Stop blind retries, persist the blocked step, and wait for the human recovery action.',
+      'Resume only after the runtime evidence shows the page has been reacquired.',
+    ],
+  },
+};
+
+const SURFACE_PROMPT_PACKS = {
+  public_content: {
+    id: 'public_content',
+    instructions: [
+      'Surface: readable public content.',
+      'Prefer inspect, extract, extract_structured, extract_batch, share_page, and continue.',
+    ],
+  },
+  public_search: {
+    id: 'public_search',
+    instructions: [
+      'Surface: public search or navigation-heavy content.',
+      'Stay conservative and extract the visible result state before deeper actions.',
+    ],
+  },
+  live_auth_session: {
+    id: 'live_auth_session',
+    instructions: [
+      'Surface: authenticated session shell without a specialized task surface yet.',
+      'Use inspect, continue, and explain_route until form or workspace evidence becomes explicit.',
+    ],
+  },
+  live_runtime_surface: {
+    id: 'live_runtime_surface',
+    instructions: [
+      'Surface: generic live runtime page.',
+      'Preserve the current session context and avoid premature specialization.',
+    ],
+  },
+  session_reentry: {
+    id: 'session_reentry',
+    instructions: [
+      'Surface: warmup and re-entry.',
+      'Focus on trust recovery and re-entry rather than content extraction or page mutation.',
+    ],
+  },
+  form_surface: {
+    id: 'form_surface',
+    instructions: [
+      'Surface: visible form.',
+      'Match labels conservatively, avoid blind writes, and keep sensitive fields out of automatic writes.',
+    ],
+  },
+  form_review_required: {
+    id: 'form_review_required',
+    instructions: [
+      'Surface: form still requires review.',
+      'Resolve blockers and review-tier fields first; do not confirm submit while the form still needs review.',
+    ],
+  },
+  form_ready_to_submit: {
+    id: 'form_ready_to_submit',
+    instructions: [
+      'Surface: form appears ready to submit.',
+      'Keep the final step explicit and use safe_submit with the required confirmation string.',
+    ],
+  },
+  workspace_surface: {
+    id: 'workspace_surface',
+    instructions: [
+      'Surface: authenticated workspace.',
+      'Inspect the visible live items and composer state before taking guarded actions.',
+    ],
+  },
+  workspace_list: {
+    id: 'workspace_list',
+    instructions: [
+      'Surface: workspace list.',
+      'Select the live item first; do not draft or execute until the target item is stable.',
+    ],
+  },
+  workspace_detail: {
+    id: 'workspace_detail',
+    instructions: [
+      'Surface: workspace detail panel.',
+      'Keep the selected item aligned with the detail view before drafting or executing.',
+    ],
+  },
+  workspace_thread: {
+    id: 'workspace_thread',
+    instructions: [
+      'Surface: workspace thread.',
+      'Draft in the active composer, keep the active item stable, and execute only through execute_action.',
+    ],
+  },
+  workspace_composer: {
+    id: 'workspace_composer',
+    instructions: [
+      'Surface: focused composer.',
+      'Draft safely, keep send guarded, and verify the result after any execution.',
+    ],
+  },
+  workspace_loading_shell: {
+    id: 'workspace_loading_shell',
+    instructions: [
+      'Surface: loading shell.',
+      'Re-inspect after the workspace stabilizes and avoid acting while the shell is still loading.',
+    ],
+  },
+  checkpoint_handoff: {
+    id: 'checkpoint_handoff',
+    instructions: [
+      'Surface: gated checkpoint or blocker.',
+      'Request handoff, stop direct action loops, and wait for the human recovery step.',
+    ],
+  },
+};
+
+export function getBoundaryPromptPack(key) {
+  return key ? BOUNDARY_PROMPT_PACKS[key] ?? null : null;
+}
+
+export function getSurfacePromptPack(key) {
+  return key ? SURFACE_PROMPT_PACKS[key] ?? null : null;
+}

package/src/server/task-frame.js

@@ -0,0 +1,11 @@
+export function createTaskFrame({ taskId, kind, maxAttempts = 3 }) {
+  return {
+    taskId,
+    kind,
+    attempts: 0,
+    maxAttempts,
+    history: [],
+    semanticBindings: new Map(),
+    nextRecovery: null,
+  };
+}

package/src/server/tasks/search-task.js

@@ -0,0 +1,321 @@
+import { getActivePage } from '../../layer1-bridge/chrome.js';
+import { typeByHintId, clickByHintId, pressKey } from '../../layer3-action/actions.js';
+import { extractMainContent, waitUntilStable } from '../content.js';
+import { observeSearchSnapshot } from '../observe.js';
+import { createTaskFrame } from '../task-frame.js';
+import { syncPageState } from '../state.js';
+import { rebindHintCandidate } from '../../layer2-perception/hints.js';
+import { NO_EFFECT, LOADING_PENDING, EXECUTION_FAILED } from '../error-codes.js';
+
+const INPUT_HINT_TYPES = new Set(['searchbox', 'textbox', 'combobox', 'input', 'textarea']);
+
+function isInputLikeHint(hint = {}) {
+  if (INPUT_HINT_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 hydrateHintCandidate(candidate, snapshot) {
+  if (!candidate?.id) return candidate ?? null;
+  const fullHint = (snapshot?.hints ?? []).find((hint) => hint.id === candidate.id);
+  return fullHint ? { ...fullHint, ...candidate, meta: { ...(fullHint.meta ?? {}), ...(candidate.meta ?? {}) } } : candidate;
+}
+
+function resolveSearchHint(snapshot, frame) {
+  const ranked = snapshot?.ranking?.search_input ?? [];
+  const rankedCandidate = ranked
+    .map((hint) => hydrateHintCandidate(hint, snapshot))
+    .find(isInputLikeHint);
+  if (rankedCandidate) return rankedCandidate;
+
+  const boundId = frame.semanticBindings.get('search_input');
+  const boundHint = (snapshot?.hints ?? []).find((hint) => hint.id === boundId);
+  if (isInputLikeHint(boundHint)) return boundHint;
+
+  return (snapshot?.hints ?? []).find(isInputLikeHint) ?? null;
+}
+
+function chooseSearchPlan(snapshot, frame) {
+  const searchHint = resolveSearchHint(snapshot, frame);
+  const submitHint = snapshot?.submitCandidate;
+  let mode = 'primary_submit';
+  if (frame.nextRecovery === 'alternate_submit') {
+    mode = 'alternate_submit';
+  } else if (frame.nextRecovery === 'reobserve') {
+    mode = 'reobserve';
+  }
+  frame.nextRecovery = null;
+  const plan = {
+    query: snapshot?.query ?? '',
+    mode,
+    searchInputHintId: searchHint?.id ?? frame.semanticBindings.get('search_input') ?? null,
+    submitHintId: submitHint?.id ?? frame.semanticBindings.get('submit_control') ?? null,
+  };
+  if (plan.searchInputHintId) {
+    frame.semanticBindings.set('search_input', plan.searchInputHintId);
+  }
+  if (plan.submitHintId) {
+    frame.semanticBindings.set('submit_control', plan.submitHintId);
+  }
+  return plan;
+}
+
+function applyRecovery(frame, verdict) {
+  if (!verdict?.error_code) return;
+  if (verdict.error_code === NO_EFFECT) {
+    frame.nextRecovery = 'alternate_submit';
+  } else if (verdict.error_code === LOADING_PENDING) {
+    frame.nextRecovery = 'wait_then_reverify';
+  } else {
+    frame.nextRecovery = 'reobserve';
+  }
+}
+
+function countExecutionToolCalls(execution) {
+  if (!execution) return 0;
+  if (typeof execution.toolCalls === 'number') {
+    return execution.toolCalls;
+  }
+  return 0;
+}
+
+function finalizeResult(frame, status, plan, verdict) {
+  const attempts = status === 'failed' ? frame.attempts : frame.attempts + 1;
+  const toolCalls = frame.history.reduce(
+    (sum, entry) => sum + countExecutionToolCalls(entry.execution),
+    0
+  );
+  const recovered = status === 'completed' && frame.history.slice(0, -1).some((entry) => entry.verdict && !entry.verdict.ok);
+  return {
+    taskId: frame.taskId,
+    status,
+    attempts,
+    toolCalls,
+    retries: Math.max(attempts - 1, 0),
+    plan,
+    verdict,
+    frame,
+    recovered,
+  };
+}
+
+function stripTrace(result) {
+  const { frame, ...publicResult } = result;
+  return publicResult;
+}
+
+function createRebuildHints(page, state) {
+  return async (hintId) => {
+    const previousHint = state.hintMap.find((hint) => hint.id === hintId);
+    await syncPageState(page, state, { force: true });
+    if (!previousHint) return null;
+    return rebindHintCandidate(previousHint, state.hintMap);
+  };
+}
+
+async function verifySearchOutcome({
+  page,
+  state,
+  plan,
+  snapshot,
+  deps = {},
+}) {
+  const prevDomRevision = snapshot?.domRevision ?? 0;
+  const prevUrl = snapshot?.url ?? (await page.url());
+  const prevContent = snapshot?.content?.text ?? '';
+  const syncState = deps.syncState ?? syncPageState;
+  await syncState(page, state, { force: true });
+  const currentDomRevision = state.pageState.domRevision;
+  const currentUrl = page.url();
+  const readyState = await page.evaluate(() => document.readyState);
+  const extractContent = deps.extractContent ?? extractMainContent;
+  const newContent = (await extractContent(page)).text;
+  const evidence = {
+    domRevision: currentDomRevision,
+    url: currentUrl,
+    content: newContent,
+    readyState,
+  };
+
+  if (
+    currentDomRevision !== prevDomRevision ||
+    currentUrl !== prevUrl ||
+    newContent !== prevContent
+  ) {
+    return { ok: true, evidence };
+  }
+
+  if (readyState !== 'complete') {
+    return { ok: false, error_code: LOADING_PENDING, evidence };
+  }
+
+  return { ok: false, error_code: NO_EFFECT, evidence };
+}
+
+async function executeSearchTask({
+  query,
+  observer,
+  executor,
+  verifier,
+  waitThenReverify,
+  maxAttempts = 3,
+  taskId,
+}) {
+  const frame = createTaskFrame({
+    taskId: taskId ?? `search-${Date.now()}`,
+    kind: 'search_task',
+    maxAttempts,
+  });
+  const waitFn = typeof waitThenReverify === 'function'
+    ? waitThenReverify
+    : async () => undefined;
+
+  for (; frame.attempts < frame.maxAttempts; frame.attempts += 1) {
+    const observerResult = await observer({ query, frame });
+    const snapshot = observerResult?.snapshot ?? observerResult;
+    const plan = chooseSearchPlan(snapshot, frame);
+    const execution = await executor(plan);
+    const verdict = await verifier({ plan, execution, snapshot, frame });
+    frame.history.push({ snapshot, plan, execution, verdict });
+
+    if (verdict.ok) {
+      return finalizeResult(frame, 'completed', plan, verdict);
+    }
+
+    if (verdict.error_code === LOADING_PENDING) {
+      await waitFn({ plan, snapshot, frame, query });
+      const retryVerdict = await verifier({ plan, execution, snapshot, frame, retry: true });
+      frame.history.push({ phase: 'wait_then_reverify', plan, verdict: retryVerdict });
+      if (retryVerdict.ok) {
+        return finalizeResult(frame, 'completed', plan, retryVerdict);
+      }
+      applyRecovery(frame, retryVerdict);
+      continue;
+    }
+
+    applyRecovery(frame, verdict);
+  }
+
+  return finalizeResult(frame, 'failed', null, null);
+}
+
+export async function runSearchTask(options) {
+  const result = await executeSearchTask(options);
+  return stripTrace(result);
+}
+
+export async function runSearchTaskTool({
+  state,
+  query,
+  max_attempts = 3,
+  deps = {},
+}) {
+  const {
+    getActivePage: getActivePageOverride,
+    observer: observerOverride,
+    executor: executorOverride,
+    verifier: verifierOverride,
+    waitThenReverify: waitThenReverifyOverride,
+    waitStableAction: waitStableActionOverride,
+    extractContentAction: extractContentActionOverride,
+    typeAction: typeActionOverride,
+    clickAction: clickActionOverride,
+    pressKeyAction: pressKeyActionOverride,
+    syncStateAction: syncStateActionOverride,
+  } = deps;
+
+  const getPage = getActivePageOverride ?? getActivePage;
+  const waitStableAction = waitStableActionOverride ?? waitUntilStable;
+  const extractContentAction = extractContentActionOverride ?? extractMainContent;
+  const typeAction = typeActionOverride ?? typeByHintId;
+  const clickAction = clickActionOverride ?? clickByHintId;
+  const pressKeyAction = pressKeyActionOverride ?? pressKey;
+  const syncStateAction = syncStateActionOverride ?? syncPageState;
+
+  const page = await getPage();
+  const rebuildHints = createRebuildHints(page, state);
+  let observer = observerOverride;
+  if (!observer) {
+    observer = ({ frame }) => observeSearchSnapshot({
+      page,
+      state,
+      query,
+      frame,
+      deps: { waitStable: waitStableAction, extractContent: extractContentAction },
+    });
+  }
+
+  let executor = executorOverride;
+  if (!executor) {
+    executor = async (plan) => {
+      if (!plan.searchInputHintId) {
+        return { ok: false, error_code: EXECUTION_FAILED };
+      }
+      let actionCount = 0;
+      try {
+        if (plan.mode === 'primary_submit') {
+          await typeAction(page, plan.searchInputHintId, query, true, { rebuildHints });
+          actionCount += 1;
+        } else if (plan.mode === 'alternate_submit') {
+          await typeAction(page, plan.searchInputHintId, query, false, { rebuildHints });
+          actionCount += 1;
+          if (plan.submitHintId) {
+            await clickAction(page, plan.submitHintId, { rebuildHints });
+            actionCount += 1;
+          } else {
+            await pressKeyAction(page, 'Enter');
+            actionCount += 1;
+          }
+        } else {
+          await pressKeyAction(page, 'Enter');
+          actionCount += 1;
+        }
+        await syncStateAction(page, state, { force: true });
+        return { ok: true, toolCalls: actionCount };
+      } catch (err) {
+        return {
+          ok: false,
+          error_code: EXECUTION_FAILED,
+          toolCalls: actionCount,
+          evidence: { message: err.message },
+        };
+      }
+    };
+  }
+
+  let verifier = verifierOverride;
+  if (!verifier) {
+    verifier = ({ plan, snapshot }) =>
+      verifySearchOutcome({
+        page,
+        state,
+        plan,
+        snapshot,
+        deps: {
+          extractContent: extractContentAction,
+          syncState: syncStateAction,
+        },
+      });
+  }
+
+  let waitThenReverify = waitThenReverifyOverride;
+  if (!waitThenReverify) {
+    waitThenReverify = async () => {
+      await waitStableAction(page, { stableChecks: 2, interval: 120, timeout: 2000 });
+    };
+  }
+
+  const result = await executeSearchTask({
+    query,
+    observer,
+    executor,
+    verifier,
+    waitThenReverify,
+    maxAttempts: max_attempts,
+    taskId: `search-tool-${Date.now()}`,
+  });
+
+  state.taskFrames.set(result.frame.taskId, result.frame);
+  return stripTrace(result);
+}