feat(core): optional intent label on interaction tools (#894)

src/mcp-server.ts

@@ -329,25 +329,6 @@ export interface MCPServerOptions {
   initialToolTier?: ToolTier;
 }
 
-
-export function summarizeMcpResultForJournal(result: MCPResult): string | undefined {
-  const content = result.content;
-  if (!Array.isArray(content)) return undefined;
-  const injectedHint = typeof (result as Record<string, unknown>)._hint === 'string'
-    ? String((result as Record<string, unknown>)._hint).trim()
-    : undefined;
-  const text = content
-    .map((part) => (part && part.type === 'text' ? part.text : ''))
-    .filter((textPart) => {
-      if (!textPart) return false;
-      return injectedHint === undefined || textPart.trim() !== injectedHint;
-    })
-    .join(' ')
-    .replace(/\s+/g, ' ')
-    .trim();
-  return text ? text.slice(0, 500) : undefined;
-}
-
 export class MCPServer {
   private tools: Map<string, ToolRegistry> = new Map();
   private resources: Map<string, MCPResourceDefinition> = new Map();
@@ -2034,24 +2015,6 @@ export class MCPServer {
       // when --secrets was not passed.
       const finalResult = redactSecrets(result);
       this.recordToolOutputObservability(toolName, finalResult);
-
-      // Record to task journal after response redaction so arbitrary literal
-      // secret values cannot be persisted in journal result summaries.
-      try {
-        const journal = getTaskJournal();
-        const entry = journal.createEntry(
-          toolName,
-          sessionId,
-          toolArgs,
-          Date.now() - toolStartTime,
-          !(finalResult as MCPResult).isError,
-          summarizeMcpResultForJournal(finalResult as MCPResult),
-        );
-        journal.record(entry);
-      } catch {
-        // Best-effort journal recording
-      }
-
       return finalResult;
     } catch (error) {
       const message = formatError(error);
@@ -2095,14 +2058,7 @@ export class MCPServer {
       // Record to task journal
       try {
         const journal = getTaskJournal();
-        const entry = journal.createEntry(
-          toolName,
-          sessionId,
-          telemetryToolArgs,
-          Date.now() - toolStartTime,
-          false,
-          redactedMessage,
-        );
+        const entry = journal.createEntry(toolName, sessionId, telemetryToolArgs, Date.now() - toolStartTime, false);
         journal.record(entry);
       } catch {
         // Best-effort journal recording

src/tools/drag-drop.ts

@@ -13,7 +13,7 @@ interface Position {
 
 const definition: MCPToolDefinition = {
   name: 'drag_drop',
-  description: 'Drag and drop by selector or coordinates.',
+  description: 'Drag and drop by selector or coordinates. Pass intent="..." (≤120 chars) to label this action in audit logs.',
   inputSchema: {
     type: 'object',
     properties: {
@@ -53,6 +53,11 @@ const definition: MCPToolDefinition = {
         type: 'number',
         description: 'Delay in ms between steps. Default: 10',
       },
+      intent: {
+        type: 'string',
+        description: 'Human-readable label for this action in audit logs (≤120 chars)',
+        maxLength: 120,
+      },
     },
     required: ['tabId'],
   },
@@ -72,6 +77,23 @@ const handler: ToolHandler = async (
   const targetY = args.targetY as number | undefined;
   const steps = (args.steps as number | undefined) ?? 10;
   const delay = (args.delay as number | undefined) ?? 10;
+  const intent = args.intent as string | undefined;
+
+  // Validate intent when provided — use typeof guard for null-safety
+  if (typeof intent === 'string') {
+    if (intent === '') {
+      return {
+        content: [{ type: 'text', text: 'INVALID_INTENT: intent must not be an empty string' }],
+        isError: true,
+      };
+    }
+    if (intent.length > 120) {
+      return {
+        content: [{ type: 'text', text: `INVALID_INTENT: intent exceeds 120 characters (got ${intent.length})` }],
+        isError: true,
+      };
+    }
+  }
 
   const sessionManager = getSessionManager();
 

src/tools/file-upload.ts

@@ -59,7 +59,7 @@ export interface UploadPathValidationResult {
 
 const definition: MCPToolDefinition = {
   name: 'file_upload',
-  description: 'Upload files to a file input element on the page.',
+  description: 'Upload files to a file input element on the page. Pass intent="..." (≤120 chars) to label this action in audit logs.',
   inputSchema: {
     type: 'object',
     properties: {
@@ -76,6 +76,11 @@ const definition: MCPToolDefinition = {
         items: { type: 'string' },
         description: 'File paths to upload. Paths must resolve under configured file_upload roots.',
       },
+      intent: {
+        type: 'string',
+        description: 'Human-readable label for this action in audit logs (≤120 chars)',
+        maxLength: 120,
+      },
     },
     required: ['tabId', 'selector', 'filePaths'],
   },
@@ -244,6 +249,23 @@ const handler: ToolHandler = async (
   const tabId = args.tabId as string;
   const selector = args.selector as string;
   const filePaths = args.filePaths as string[];
+  const intent = args.intent as string | undefined;
+
+  // Validate intent when provided — use typeof guard for null-safety
+  if (typeof intent === 'string') {
+    if (intent === '') {
+      return {
+        content: [{ type: 'text', text: 'INVALID_INTENT: intent must not be an empty string' }],
+        isError: true,
+      };
+    }
+    if (intent.length > 120) {
+      return {
+        content: [{ type: 'text', text: `INVALID_INTENT: intent exceeds 120 characters (got ${intent.length})` }],
+        isError: true,
+      };
+    }
+  }
 
   const sessionManager = getSessionManager();
 

src/tools/fill-form.ts

@@ -19,15 +19,10 @@ import { humanType, humanMouseMove } from '../stealth/human-behavior';
 import { detectLoginOutcome, LoginDetectResult } from './login-detector';
 import { wrapMutatingHandler } from '../utils/snapshot-cache-helper';
 import { coerceVerifyMode, runVerify, VERIFY_FIELD_SCHEMA } from '../core/perception/verify';
-import {
-  appendReturnAfterState,
-  parseReturnAfterState,
-  RETURN_AFTER_STATE_SCHEMA,
-} from './_shared/return-after-state';
 
 const definition: MCPToolDefinition = {
   name: 'fill_form',
-  description: 'Fill form fields and optionally submit.',
+  description: 'Fill form fields and optionally submit. Pass intent="..." (≤120 chars) to label this action in audit logs.',
   inputSchema: {
     type: 'object',
     properties: {
@@ -72,7 +67,11 @@ const definition: MCPToolDefinition = {
         additionalProperties: { type: 'string' },
       },
       verify: VERIFY_FIELD_SCHEMA,
-      returnAfterState: RETURN_AFTER_STATE_SCHEMA,
+      intent: {
+        type: 'string',
+        description: 'Human-readable label for this action in audit logs (≤120 chars)',
+        maxLength: 120,
+      },
     },
     required: ['tabId'],
   },
@@ -94,7 +93,23 @@ const handler: ToolHandler = async (
   const pollInterval = Math.min(Math.max((args.pollInterval as number) || 300, 50), 2000);
   const loginCheck: 'auto' | 'off' = (args.loginCheck === 'off') ? 'off' : 'auto';
   const verifyMode = coerceVerifyMode(args.verify);
-  const returnAfterState = parseReturnAfterState(args.returnAfterState);
+  const intent = args.intent as string | undefined;
+
+  // Validate intent when provided — use typeof guard for null-safety
+  if (typeof intent === 'string') {
+    if (intent === '') {
+      return {
+        content: [{ type: 'text', text: 'INVALID_INTENT: intent must not be an empty string' }],
+        isError: true,
+      };
+    }
+    if (intent.length > 120) {
+      return {
+        content: [{ type: 'text', text: `INVALID_INTENT: intent exceeds 120 characters (got ${intent.length})` }],
+        isError: true,
+      };
+    }
+  }
 
   const sessionManager = getSessionManager();
 
@@ -627,7 +642,7 @@ const handler: ToolHandler = async (
     if (detectorFailedLogin) errorReason = 'login_failed';
     else if (submitFailed) errorReason = 'submit_failed';
 
-    const fillFormResult: MCPResult = {
+    return {
       content: [
         {
           type: 'text',
@@ -643,14 +658,6 @@ const handler: ToolHandler = async (
           : {}),
       ...(fillVerifyReport ? { verify: fillVerifyReport } : {}),
     } as MCPResult;
-    // Snapshot capture happens after the post-action wait inside withDomDelta
-    // (and the optional login-detector poll), so the snapshot reflects the
-    // post-action DOM. Only attach on non-error results — when fill_form
-    // failed there is no point paying for an extra snapshot.
-    if (!isError) {
-      await appendReturnAfterState(fillFormResult, page, sessionId, tabId, returnAfterState, context);
-    }
-    return fillFormResult;
   } catch (error) {
     return {
       content: [

src/tools/form-input.ts

@@ -7,11 +7,10 @@ import { MCPToolDefinition, MCPResult, ToolHandler, ToolContext, hasBudget } fro
 import { getSessionManager } from '../session-manager';
 import { getRefIdManager, formatStaleRefError, makeStaleRefError } from '../utils/ref-id-manager';
 import { withDomDelta } from '../utils/dom-delta';
-import { wrapMutatingHandler } from '../utils/snapshot-cache-helper';
 
 const definition: MCPToolDefinition = {
   name: 'form_input',
-  description: 'Set one form element value by ref.\n\nWhen to use: Filling a single known input, textarea, select, or checkbox by ref.\nWhen NOT to use: Use fill_form({fields:{...}}) for multiple fields or optional submit.',
+  description: 'Set one form element value by ref. Pass intent="..." (≤120 chars) to label this action in audit logs.\n\nWhen to use: Filling a single known input, textarea, select, or checkbox by ref.\nWhen NOT to use: Use fill_form({fields:{...}}) for multiple fields or optional submit.',
   inputSchema: {
     type: 'object',
     properties: {
@@ -27,6 +26,11 @@ const definition: MCPToolDefinition = {
         type: 'string',
         description: 'Value to set. Checkboxes: "true"/"false"',
       },
+      intent: {
+        type: 'string',
+        description: 'Human-readable label for this action in audit logs (≤120 chars)',
+        maxLength: 120,
+      },
     },
     required: ['ref', 'value', 'tabId'],
   },
@@ -40,6 +44,23 @@ const handler: ToolHandler = async (
   const tabId = args.tabId as string;
   const ref = args.ref as string;
   const value = args.value;
+  const intent = args.intent as string | undefined;
+
+  // Validate intent when provided — use typeof guard for null-safety
+  if (typeof intent === 'string') {
+    if (intent === '') {
+      return {
+        content: [{ type: 'text', text: 'INVALID_INTENT: intent must not be an empty string' }],
+        isError: true,
+      };
+    }
+    if (intent.length > 120) {
+      return {
+        content: [{ type: 'text', text: `INVALID_INTENT: intent exceeds 120 characters (got ${intent.length})` }],
+        isError: true,
+      };
+    }
+  }
 
   const sessionManager = getSessionManager();
   const refIdManager = getRefIdManager();
@@ -433,10 +454,5 @@ const handler: ToolHandler = async (
 };
 
 export function registerFormInputTool(server: MCPServer): void {
-  // Snapshot-cache (#879): bump docEpoch after every successful set.
-  const sm = getSessionManager();
-  const wrapped = wrapMutatingHandler(handler, (sid, tid) =>
-    tid ? sm.getPage(sid, tid) : Promise.resolve(null),
-  );
-  server.registerTool('form_input', wrapped, definition);
+  server.registerTool('form_input', handler, definition);
 }