@yuzc-001/grasp 0.6.6

package/src/server/prompt-assembly.js

@@ -0,0 +1,148 @@
+import { buildAgentBoundary } from './route-boundary.js';
+import { getBoundaryPromptPack, getSurfacePromptPack } from './surface-prompts.js';
+
+function getPageRole(page = {}) {
+  return page?.page_role ?? page?.current_role ?? page?.currentRole ?? null;
+}
+
+function formatList(items = []) {
+  return Array.isArray(items) && items.length > 0
+    ? items.map((item) => `- ${item}`).join('\n')
+    : '- none';
+}
+
+function readWorkspaceSurface(result = {}, route = {}, page = {}) {
+  return result?.workspace?.workspace_surface
+    ?? result?.snapshot?.workspace_surface
+    ?? route?.evidence?.workspace_surface
+    ?? page?.workspace_surface
+    ?? page?.workspaceSurface
+    ?? null;
+}
+
+function inferPromptSurfaceKey({ boundaryKey, status, result = {}, route = {}, page = {} } = {}) {
+  if (!boundaryKey) return null;
+
+  if (boundaryKey === 'public_read') {
+    return getPageRole(page) === 'search' ? 'public_search' : 'public_content';
+  }
+
+  if (boundaryKey === 'live_session') {
+    return getPageRole(page) === 'auth' ? 'live_auth_session' : 'live_runtime_surface';
+  }
+
+  if (boundaryKey === 'session_warmup') {
+    return 'session_reentry';
+  }
+
+  if (boundaryKey === 'form_runtime') {
+    const completionStatus = result?.form?.completion_status ?? null;
+    if (completionStatus === 'review_required') return 'form_review_required';
+    if (completionStatus === 'ready_to_submit' || completionStatus === 'complete') {
+      return 'form_ready_to_submit';
+    }
+    return 'form_surface';
+  }
+
+  if (boundaryKey === 'workspace_runtime') {
+    const workspaceSurface = readWorkspaceSurface(result, route, page);
+    if (workspaceSurface === 'list') return 'workspace_list';
+    if (workspaceSurface === 'detail') return 'workspace_detail';
+    if (workspaceSurface === 'thread') return 'workspace_thread';
+    if (workspaceSurface === 'composer') return 'workspace_composer';
+    if (workspaceSurface === 'loading_shell') return 'workspace_loading_shell';
+    return 'workspace_surface';
+  }
+
+  if (boundaryKey === 'handoff') {
+    return 'checkpoint_handoff';
+  }
+
+  if (status === 'gated') {
+    return 'checkpoint_handoff';
+  }
+
+  return null;
+}
+
+function buildSegment(id, lines) {
+  return {
+    id,
+    text: lines.filter(Boolean).join('\n'),
+  };
+}
+
+export function buildAgentPrompt({
+  status,
+  page,
+  result = {},
+  continuation = {},
+  route = null,
+  agentBoundary = null,
+} = {}) {
+  const boundary = agentBoundary ?? buildAgentBoundary({
+    status,
+    page,
+    result,
+    continuation,
+    route,
+  });
+  if (!boundary) return null;
+
+  const boundaryPack = getBoundaryPromptPack(boundary.key);
+  const surfaceKey = inferPromptSurfaceKey({
+    boundaryKey: boundary.key,
+    status,
+    result,
+    route,
+    page,
+  });
+  const surfacePack = getSurfacePromptPack(surfaceKey);
+  const nextStep = boundary.next_step ?? continuation?.suggested_next_action ?? null;
+
+  const segments = [
+    buildSegment('runtime_identity', [
+      'You are operating inside Grasp, a route-aware browser runtime.',
+      'Respect the current runtime boundary, keep actions explainable, and switch modes only when runtime evidence changes.',
+    ]),
+    buildSegment(`boundary_${boundary.key}`, [
+      `Current boundary: ${boundary.key}`,
+      `Boundary summary: ${boundary.summary}`,
+      'Preferred tools:',
+      formatList(boundary.preferred_tools),
+      'Avoid:',
+      formatList(boundary.avoid),
+      boundary.confirmation ? `Explicit confirmation gate: ${boundary.confirmation}` : null,
+    ]),
+    boundaryPack
+      ? buildSegment(`boundary_pack_${boundaryPack.id}`, [
+        `Boundary pack: ${boundaryPack.id}`,
+        ...boundaryPack.instructions.map((line) => `- ${line}`),
+      ])
+      : null,
+    surfacePack
+      ? buildSegment(`surface_pack_${surfacePack.id}`, [
+        `Surface pack: ${surfacePack.id}`,
+        ...surfacePack.instructions.map((line) => `- ${line}`),
+      ])
+      : null,
+    buildSegment('next_step', [
+      `Next best step: ${nextStep ?? 'unknown'}`,
+    ]),
+  ].filter(Boolean);
+
+  return {
+    boundary_key: boundary.key,
+    surface_key: surfaceKey,
+    prompt_pack: {
+      boundary: boundaryPack?.id ?? boundary.key,
+      surface: surfacePack?.id ?? surfaceKey ?? null,
+    },
+    preferred_tools: [...boundary.preferred_tools],
+    avoid: [...boundary.avoid],
+    confirmation: boundary.confirmation,
+    next_step: nextStep,
+    segments,
+    system_prompt: segments.map((segment) => segment.text).join('\n\n'),
+  };
+}

package/src/server/responses.js

@@ -0,0 +1,44 @@
+function normalizeText(value) {
+  if (Array.isArray(value)) {
+    return value.filter((line) => line !== undefined && line !== null && line !== '').join('\n');
+  }
+
+  return String(value ?? '');
+}
+
+export function textResponse(value, meta) {
+  const response = {
+    content: [
+      {
+        type: 'text',
+        text: normalizeText(value),
+      },
+    ],
+  };
+
+  if (meta && Object.keys(meta).length > 0) {
+    response.meta = meta;
+  }
+
+  return response;
+}
+
+export function errorResponse(value, meta = {}) {
+  return {
+    ...textResponse(value, meta),
+    isError: true,
+  };
+}
+
+export function imageResponse(data, mimeType = 'image/png') {
+  const base64 = Buffer.isBuffer(data) ? data.toString('base64') : String(data);
+  return {
+    content: [
+      {
+        type: 'image',
+        data: base64,
+        mimeType,
+      },
+    ],
+  };
+}

package/src/server/route-boundary.js

@@ -0,0 +1,174 @@
+const BOUNDARY_TEMPLATES = {
+  public_read: {
+    summary: 'Stay on the read/extract path. Prefer inspect, extract, extract_structured, extract_batch, share_page, and continue before low-level actions.',
+    preferred_tools: ['inspect', 'extract', 'extract_structured', 'extract_batch', 'share_page', 'continue'],
+    avoid: ['page-changing actions', 'form_runtime tools', 'workspace_runtime tools'],
+    confirmation: null,
+    next_step: 'inspect',
+  },
+  live_session: {
+    summary: 'Stay on the live session runtime loop. Prefer inspect, extract, continue, and explain_route until a specialized surface is clearly present.',
+    preferred_tools: ['inspect', 'extract', 'continue', 'explain_route'],
+    avoid: ['premature low-level primitives', 'form_runtime tools without a form surface', 'workspace_runtime tools without a workspace surface'],
+    confirmation: null,
+    next_step: 'inspect',
+  },
+  session_warmup: {
+    summary: 'Warm the session before direct entry. Use preheat_session first, then re-enter the runtime loop after trust improves.',
+    preferred_tools: ['preheat_session', 'entry', 'inspect'],
+    avoid: ['repeated direct retries', 'form_runtime tools', 'workspace_runtime tools'],
+    confirmation: null,
+    next_step: 'preheat_session',
+  },
+  form_runtime: {
+    summary: 'Use the form surface. Fill safe text fields first, keep review-tier controls explicit, and submit only through safe_submit.',
+    preferred_tools: ['form_inspect', 'fill_form', 'set_option', 'set_date', 'verify_form', 'safe_submit'],
+    avoid: ['blind field writes', 'raw submit clicks', 'navigate away mid-form'],
+    confirmation: 'safe_submit(mode="confirm", confirmation="SUBMIT")',
+    next_step: 'verify_form',
+  },
+  workspace_runtime: {
+    summary: 'Use the workspace surface. Select the live item, draft safely, preview sends, and execute only through execute_action.',
+    preferred_tools: ['workspace_inspect', 'select_live_item', 'draft_action', 'execute_action', 'verify_outcome'],
+    avoid: ['raw send clicks', 'press Enter to send', 'execute before draft or preview'],
+    confirmation: 'execute_action(mode="confirm", confirmation="EXECUTE")',
+    next_step: 'workspace_inspect',
+  },
+  handoff: {
+    summary: 'This flow is blocked on handoff. Stop direct action attempts, persist the handoff step, let the human recover the page, then resume.',
+    preferred_tools: ['request_handoff', 'mark_handoff_in_progress', 'mark_handoff_done', 'resume_after_handoff', 'continue'],
+    avoid: ['looping retries', 'form_runtime actions while gated', 'workspace_runtime actions while gated'],
+    confirmation: null,
+    next_step: 'request_handoff',
+  },
+};
+
+function getPageRole(page = null) {
+  return page?.page_role ?? page?.current_role ?? page?.currentRole ?? null;
+}
+
+export function inferSurfaceBoundaryKey({
+  result = {},
+  route = null,
+  page = null,
+} = {}) {
+  if (result?.task_kind === 'form' || route?.selected_mode === 'form_runtime') {
+    return 'form_runtime';
+  }
+
+  if (result?.task_kind === 'workspace' || route?.selected_mode === 'workspace_runtime') {
+    return 'workspace_runtime';
+  }
+
+  if (route?.selected_mode === 'public_read') {
+    return 'public_read';
+  }
+
+  if (route?.selected_mode === 'live_session') {
+    return 'live_session';
+  }
+
+  const pageRole = getPageRole(page);
+  if (pageRole === 'form') {
+    return 'form_runtime';
+  }
+  if (pageRole === 'workspace') {
+    return 'workspace_runtime';
+  }
+  if (pageRole === 'auth') {
+    return 'live_session';
+  }
+  if (['content', 'docs', 'search', 'navigation-heavy'].includes(String(pageRole ?? ''))) {
+    return 'public_read';
+  }
+
+  return null;
+}
+
+export function inferAgentBoundaryKey({
+  status,
+  result = {},
+  continuation = {},
+  route = null,
+  page = null,
+} = {}) {
+  if (
+    status === 'handoff_required'
+    || status === 'gated'
+    || route?.selected_mode === 'handoff'
+    || continuation?.suggested_next_action === 'request_handoff'
+  ) {
+    return 'handoff';
+  }
+
+  if (result?.task_kind === 'form' || route?.selected_mode === 'form_runtime') {
+    return 'form_runtime';
+  }
+
+  if (result?.task_kind === 'workspace' || route?.selected_mode === 'workspace_runtime') {
+    return 'workspace_runtime';
+  }
+
+  if (status === 'warmup' || continuation?.suggested_next_action === 'preheat_session') {
+    return 'session_warmup';
+  }
+
+  return inferSurfaceBoundaryKey({ result, route, page });
+}
+
+export function getBoundaryDefaultNextStep(key) {
+  return BOUNDARY_TEMPLATES[key]?.next_step ?? null;
+}
+
+export function buildBoundaryContinuation(key, handoffState = 'idle') {
+  if (!key) {
+    return {
+      can_continue: false,
+      suggested_next_action: null,
+      handoff_state: handoffState,
+    };
+  }
+
+  return {
+    can_continue: key !== 'handoff',
+    suggested_next_action: getBoundaryDefaultNextStep(key),
+    handoff_state: handoffState,
+  };
+}
+
+export function buildBoundaryMismatchLines({
+  toolName,
+  expectedBoundary,
+  currentBoundary,
+  nextStep = null,
+} = {}) {
+  return [
+    `Boundary mismatch: ${toolName} requires ${expectedBoundary}, but the current surface is ${currentBoundary}.`,
+    nextStep ? `Recover by running ${nextStep} before trying ${toolName} again.` : null,
+  ].filter(Boolean);
+}
+
+export function buildAgentBoundary(input = {}) {
+  const key = inferAgentBoundaryKey(input);
+  if (!key) return null;
+
+  const template = BOUNDARY_TEMPLATES[key];
+  return {
+    key,
+    summary: template.summary,
+    preferred_tools: [...template.preferred_tools],
+    avoid: [...template.avoid],
+    confirmation: template.confirmation,
+    next_step: input?.continuation?.suggested_next_action ?? template.next_step ?? null,
+  };
+}
+
+export function buildAgentBoundaryLines(boundary) {
+  if (!boundary) return [];
+
+  return [
+    `Boundary: ${boundary.key}`,
+    `Boundary guidance: ${boundary.summary}`,
+    boundary.confirmation ? `Boundary confirmation: ${boundary.confirmation}` : null,
+  ].filter(Boolean);
+}

package/src/server/route-policy.js

@@ -0,0 +1,168 @@
+function isBlockedHandoffState(handoffState) {
+  return handoffState === 'handoff_required'
+    || handoffState === 'handoff_in_progress'
+    || handoffState === 'awaiting_reacquisition';
+}
+
+function buildEvidence({
+  intent,
+  selection,
+  preflight,
+  pageState,
+  handoff,
+  triggers,
+}) {
+  return {
+    intent,
+    engine: selection?.engine ?? 'runtime',
+    session_trust: preflight?.session_trust ?? 'unknown',
+    recommended_entry_strategy: preflight?.recommended_entry_strategy ?? 'direct',
+    page_role: pageState?.currentRole ?? 'unknown',
+    workspace_surface: pageState?.workspaceSurface ?? null,
+    handoff_state: handoff?.state ?? 'idle',
+    risk_gate_detected: pageState?.riskGateDetected ?? false,
+    triggers,
+  };
+}
+
+function inferIntentFromPageState(pageState = {}, lastIntent = null) {
+  if (lastIntent) return lastIntent;
+
+  const currentRole = pageState?.currentRole ?? 'unknown';
+  if (currentRole === 'workspace' || pageState?.workspaceSurface != null) {
+    return 'workspace';
+  }
+  if (currentRole === 'form' || currentRole === 'auth') {
+    return 'submit';
+  }
+  return 'extract';
+}
+
+export function resolveRouteIntent({ intent = null, pageState = {}, lastIntent = null } = {}) {
+  return inferIntentFromPageState(pageState, intent ?? lastIntent);
+}
+
+export function decideRoute({
+  url,
+  intent = 'extract',
+  selection = {},
+  preflight = {},
+  pageState = {},
+  handoff = {},
+} = {}) {
+  const handoffState = handoff?.state ?? 'idle';
+  const currentRole = pageState?.currentRole ?? 'unknown';
+  const workspaceLike = currentRole === 'workspace' || pageState?.workspaceSurface != null;
+  const formLike = currentRole === 'form' || currentRole === 'auth';
+
+  if (isBlockedHandoffState(handoffState) || pageState?.riskGateDetected || currentRole === 'checkpoint') {
+    return {
+      policy_template: 'gated_handoff',
+      selected_mode: 'handoff',
+      confidence: 'high',
+      evidence: buildEvidence({
+        intent,
+        selection,
+        preflight,
+        pageState,
+        handoff,
+        triggers: ['gated_page_or_handoff_state'],
+      }),
+      alternatives: [],
+      fallback_chain: [],
+      requires_human: true,
+      risk_level: 'high',
+      next_step: 'request_handoff',
+    };
+  }
+
+  if (intent === 'workspace' || workspaceLike) {
+    return {
+      policy_template: 'dynamic_workspace',
+      selected_mode: 'workspace_runtime',
+      confidence: intent === 'workspace' ? 'high' : 'medium',
+      evidence: buildEvidence({
+        intent,
+        selection,
+        preflight,
+        pageState,
+        handoff,
+        triggers: [intent === 'workspace' ? 'workspace_intent' : 'workspace_surface'],
+      }),
+      alternatives: [
+        { mode: 'handoff', reason: 'human_required_if_workspace_progress_blocks' },
+      ],
+      fallback_chain: ['handoff'],
+      requires_human: false,
+      risk_level: 'medium',
+      next_step: 'workspace_inspect',
+    };
+  }
+
+  if (intent === 'submit' || formLike) {
+    return {
+      policy_template: 'real_form',
+      selected_mode: 'form_runtime',
+      confidence: intent === 'submit' ? 'high' : 'medium',
+      evidence: buildEvidence({
+        intent,
+        selection,
+        preflight,
+        pageState,
+        handoff,
+        triggers: [intent === 'submit' ? 'submit_intent' : 'form_surface'],
+      }),
+      alternatives: [
+        { mode: 'handoff', reason: 'human_required_for_sensitive_or_blocked_form_steps' },
+      ],
+      fallback_chain: ['handoff'],
+      requires_human: false,
+      risk_level: 'high',
+      next_step: 'form_inspect',
+    };
+  }
+
+  if ((intent === 'read' || intent === 'extract' || intent === 'collect') && selection?.engine === 'data') {
+    return {
+      policy_template: 'public_content',
+      selected_mode: 'public_read',
+      confidence: 'high',
+      evidence: buildEvidence({
+        intent,
+        selection,
+        preflight,
+        pageState,
+        handoff,
+        triggers: ['public_read_engine'],
+      }),
+      alternatives: [
+        { mode: 'live_session', reason: 'browser_reuse_if_public_read_is_insufficient' },
+      ],
+      fallback_chain: ['live_session'],
+      requires_human: false,
+      risk_level: 'low',
+      next_step: 'extract',
+    };
+  }
+
+  return {
+    policy_template: 'authenticated_content',
+    selected_mode: 'live_session',
+    confidence: preflight?.session_trust === 'high' ? 'high' : 'medium',
+    evidence: buildEvidence({
+      intent,
+      selection,
+      preflight,
+      pageState,
+      handoff,
+      triggers: ['runtime_default'],
+    }),
+    alternatives: [
+      { mode: 'handoff', reason: 'human_required_if_runtime_progress_blocks' },
+    ],
+    fallback_chain: ['handoff'],
+    requires_human: false,
+    risk_level: intent === 'act' ? 'medium' : 'low',
+    next_step: 'inspect',
+  };
+}

package/src/server/runtime-confirmation.js

@@ -0,0 +1,87 @@
+import { errorResponse, textResponse } from './responses.js';
+
+const INSTANCE_CONFIRMATION_ERROR = 'INSTANCE_CONFIRMATION_REQUIRED';
+
+function buildInstanceKey(instance = {}) {
+  return [
+    instance.display ?? 'unknown',
+    instance.browser ?? 'unknown',
+    instance.protocolVersion ?? 'unknown',
+  ].join('|');
+}
+
+export function getRuntimeConfirmation(state) {
+  return state?.runtimeConfirmation ?? null;
+}
+
+export function isRuntimeInstanceConfirmed(state, instance) {
+  const confirmation = getRuntimeConfirmation(state);
+  if (!confirmation || !instance) return false;
+  return confirmation.instance_key === buildInstanceKey(instance);
+}
+
+export function storeRuntimeConfirmation(state, instance) {
+  const confirmation = {
+    instance_key: buildInstanceKey(instance),
+    display: instance?.display ?? 'unknown',
+    browser: instance?.browser ?? null,
+    protocolVersion: instance?.protocolVersion ?? null,
+    confirmed_at: Date.now(),
+  };
+  state.runtimeConfirmation = confirmation;
+  return confirmation;
+}
+
+export function getRuntimeConfirmationSummary(state, instance) {
+  const confirmation = getRuntimeConfirmation(state);
+  if (!confirmation) {
+    return { confirmed: false, reason: 'unconfirmed' };
+  }
+  if (!instance) {
+    return { confirmed: false, reason: 'instance_unavailable', confirmation };
+  }
+  if (confirmation.instance_key !== buildInstanceKey(instance)) {
+    return { confirmed: false, reason: 'instance_changed', confirmation };
+  }
+  return { confirmed: true, reason: 'confirmed', confirmation };
+}
+
+export function requireConfirmedRuntimeInstance(state, instance, tool) {
+  if (!instance) {
+    return null;
+  }
+
+  if (isRuntimeInstanceConfirmed(state, instance)) {
+    return null;
+  }
+
+  const summary = getRuntimeConfirmationSummary(state, instance);
+  const reasonText = summary.reason === 'instance_changed'
+    ? 'The runtime instance changed after the last confirmation.'
+    : 'The runtime instance has not been confirmed yet.';
+
+  return errorResponse([
+    'Runtime instance confirmation required.',
+    `Tool: ${tool}`,
+    ...(instance?.browser ? [`Current browser: ${instance.browser}`] : []),
+    ...(instance?.display ? [`Current instance mode: ${instance.display}`] : []),
+    reasonText,
+    'Call confirm_runtime_instance first, then retry the action.',
+  ], {
+    error_code: INSTANCE_CONFIRMATION_ERROR,
+    retryable: true,
+    suggested_next_step: 'confirm_runtime_instance',
+    instance,
+    confirmation: summary,
+  });
+}
+
+export function buildRuntimeConfirmationSuccessResponse(confirmation, instance) {
+  return textResponse([
+    `Runtime instance confirmed: ${confirmation.display}`,
+    ...(instance?.browser ? [`Browser: ${instance.browser}`] : []),
+  ], {
+    confirmation,
+    instance,
+  });
+}

package/src/server/runtime-status.js

@@ -0,0 +1,7 @@
+export {
+  RUNTIME_STATUS_PATH,
+  readRuntimeStatus,
+  readRuntimeTruth,
+  writeRuntimeStatus,
+  writeRuntimeTruth,
+} from '../runtime/truth/snapshot.js';