imprint-mcp 0.4.4 → 0.4.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "imprint-mcp",
-  "version": "0.4.4",
+  "version": "0.4.6",
   "description": "Teach an AI agent how to use any website. Once. Records a real browser session + narration; generates a deterministic MCP tool plus a DOM-replay playbook fallback.",
   "type": "module",
   "exports": {

package/prompts/request-triage.md

@@ -13,6 +13,9 @@ You receive a JSON object:
   "narration": [
     { "timestamp": ms, "text": "what the user said they were doing" }
   ],
+  "events": [
+    { "seq": int, "timestamp": ms, "type": "click|input|change|submit|navigation", "detail": "truncated browser event detail" }
+  ],
   "requests": [
     {
       "seq": int,
@@ -35,6 +38,9 @@ You receive a JSON object:
 ```
 
 The narration is the user's own description of what they did. Use it to understand the workflow's intent, then select the requests that serve that intent.
+The events are the browser actions captured during recording. Use input/change/submit
+event timestamps to disambiguate repeated endpoint calls when narration was spoken
+after the action.
 
 Request entries may include `repeatCount`, `repeatedSeqs`, and `lastTimestamp` when identical requests were compacted. Select the representative `seq` unless a specific repeated seq is needed for an intentional multi-step workflow.
 
@@ -46,6 +52,7 @@ Request entries may include `repeatCount`, `repeatedSeqs`, and `lastTimestamp` w
 - Data fetches that populate the page the user cared about
 - Navigation documents (the HTML pages the user visited)
 - Lookup or resolution endpoints (anything that converts user input into structured data -- e.g. returning locations, IDs, or options the user selects from)
+- **Credential-bearing requests** -- any request whose body or headers contain `${credential.username}`, `${credential.password}`, or other `${credential.*}` placeholders. These are login/auth requests critical for downstream compilation. Always include them, even if they look like duplicates of other login requests to the same endpoint.
 
 **What to EXCLUDE** (even if same-origin):
 - Analytics and telemetry (`/collect`, `/event`, `/track`, `/log`, `/beacon`, `/pixel`, `analytics`, `telemetry`, `metrics`)
@@ -61,9 +68,12 @@ Request entries may include `repeatCount`, `repeatedSeqs`, and `lastTimestamp` w
 
 1. **Read the narration first.** It tells you the user's goal -- "searching for flights," "booking a hotel," "checking prices." Every request you select should serve that goal.
 2. **Correlate timestamps.** The narration has timestamps; the requests have timestamps. A request whose timestamp falls near a narration event ("now I clicked search") is likely load-bearing.
-3. **Prefer POST/PUT/PATCH over GET** when both exist for the same endpoint -- the mutation is usually the load-bearing one.
-4. **When in doubt, include it.** A false positive (including a noise request) is cheaper than a false negative (excluding the result-bearing XHR). The downstream compilation LLM can ignore noise, but it can't work with data it never sees.
-5. **Aim for 5-50 requests** out of potentially hundreds. If you're selecting more than 50, you're probably not filtering aggressively enough. If fewer than 3, double-check you haven't dropped the key data-fetch.
+3. **Use browser events for repeated calls.** If the same endpoint appears more
+   than once with different user-controlled values, keep the request closest to
+   the input/change/submit event, even if narration came later.
+4. **Prefer POST/PUT/PATCH over GET** when both exist for the same endpoint -- the mutation is usually the load-bearing one.
+5. **When in doubt, include it.** A false positive (including a noise request) is cheaper than a false negative (excluding the result-bearing XHR). The downstream compilation LLM can ignore noise, but it can't work with data it never sees.
+6. **Aim for 5-50 requests** out of potentially hundreds. If you're selecting more than 50, you're probably not filtering aggressively enough. If fewer than 3, double-check you haven't dropped the key data-fetch.
 
 ## Output
 

package/src/imprint/claude-cli-compile.ts

@@ -257,6 +257,7 @@ async function runClaudeCliAttempt(opts: CompileViaClaudeCliOptions): Promise<Co
             ? ['--shared-modules-json', JSON.stringify(opts.sharedModules)]
             : []),
         ],
+        alwaysLoad: true,
       },
     },
   };

package/src/imprint/compile.ts

@@ -31,6 +31,7 @@ import { redactSession } from './redact.ts';
 import { compactRequestContexts, requestContextDigest } from './request-context.ts';
 import { ensureImprintRuntimeLink } from './runtime-link.ts';
 import type { ClassifiedValue } from './session-diff.ts';
+import { isTelemetryRequest } from './telemetry.ts';
 import type { SharedCompileContext, ToolCandidate } from './tool-candidates.ts';
 import { setSpanAttributes, traced } from './tracing.ts';
 import {
@@ -280,6 +281,19 @@ function safeUrl(s: string): URL | null {
   }
 }
 
+// ─── Credential-bearing request detection ───────────────────────────────────
+
+const CREDENTIAL_PLACEHOLDER_RE = /\$\{credential\.[^}]+\}/;
+
+export function findCredentialBearingSeqs(session: Session): number[] {
+  const seqs: number[] = [];
+  for (const r of session.requests) {
+    const text = `${r.url}\n${JSON.stringify(r.headers)}\n${r.body ?? ''}`;
+    if (CREDENTIAL_PLACEHOLDER_RE.test(text)) seqs.push(r.seq);
+  }
+  return seqs;
+}
+
 // ─── triageRequests (LLM-based request filtering) ───────────────────────────
 
 const TRIAGE_RESOURCE_TYPES = new Set(['XHR', 'Fetch', 'Document']);
@@ -288,6 +302,20 @@ const HEADER_TRUNCATE_LIMIT = 200;
 // data-bearing POSTs (search/booking) from telemetry; full bodies on a busy
 // site can total >1MB and blow the 200K-token cap on `claude-opus-4-8`.
 const TRIAGE_BODY_LIMIT = 500;
+const TRIAGE_ACTION_ALIGNMENT_BEFORE_MS = 1000;
+const TRIAGE_ACTION_ALIGNMENT_AFTER_MS = 5000;
+const TRIAGE_CONTEXT_EVENT_TYPES = new Set<Session['events'][number]['type']>([
+  'navigation',
+  'click',
+  'input',
+  'change',
+  'submit',
+]);
+const TRIAGE_ACTION_EVENT_TYPES = new Set<Session['events'][number]['type']>([
+  'input',
+  'change',
+  'submit',
+]);
 
 export interface TriageResult {
   session: Session;
@@ -317,6 +345,13 @@ interface TriageRequestContext {
   lastTimestamp?: number;
 }
 
+interface TriageEventContext {
+  seq: number;
+  timestamp: number;
+  type: Session['events'][number]['type'];
+  detail: string;
+}
+
 export async function triageRequests(
   session: Session,
   llmConfig?: LLMOptions,
@@ -369,6 +404,7 @@ export async function triageRequests(
         site: session.site,
         url: session.url,
         narration: session.narration,
+        events: buildTriageEventContexts(session),
         requests: metadata,
       };
 
@@ -408,7 +444,8 @@ export async function triageRequests(
         );
       }
 
-      const selectedSet = new Set([...(seqs as number[]), ...preserveSeqs]);
+      const rescuedSeqs = rescueActionAlignedRepeatedSeqs(session, seqs as number[], compacted);
+      const selectedSet = new Set([...(seqs as number[]), ...rescuedSeqs, ...preserveSeqs]);
       const triaged: Session = {
         ...session,
         requests: session.requests.filter((r) => selectedSet.has(r.seq)),
@@ -436,6 +473,63 @@ export async function triageRequests(
   );
 }
 
+export function buildTriageEventContexts(session: Session): TriageEventContext[] {
+  return session.events
+    .filter((event) => TRIAGE_CONTEXT_EVENT_TYPES.has(event.type))
+    .map((event) => ({
+      seq: event.seq,
+      timestamp: event.timestamp,
+      type: event.type,
+      detail: truncate(event.detail, TRIAGE_BODY_LIMIT) ?? '',
+    }));
+}
+
+export function rescueActionAlignedRepeatedSeqs(
+  session: Session,
+  selectedSeqs: Iterable<number>,
+  compactedRequests: TriageRequestContext[],
+): number[] {
+  const selectedSet = new Set(selectedSeqs);
+  const requestBySeq = new Map(session.requests.map((request) => [request.seq, request]));
+  const actionTimestamps = session.events
+    .filter((event) => TRIAGE_ACTION_EVENT_TYPES.has(event.type))
+    .map((event) => event.timestamp);
+  if (actionTimestamps.length === 0) return [];
+
+  const rescued = new Set<number>();
+  for (const request of compactedRequests) {
+    const repeatedSeqs = request.repeatedSeqs ?? [];
+    if (repeatedSeqs.length === 0) continue;
+    if (!selectedSet.has(request.seq) && !repeatedSeqs.some((seq) => selectedSet.has(seq))) {
+      continue;
+    }
+
+    for (const seq of repeatedSeqs) {
+      if (selectedSet.has(seq)) continue;
+      const original = requestBySeq.get(seq);
+      if (!original) continue;
+      if (!isTriageRescueCandidate(original)) continue;
+      if (!isNearActionEvent(original.timestamp, actionTimestamps)) continue;
+      rescued.add(seq);
+    }
+  }
+
+  return [...rescued].sort((a, b) => a - b);
+}
+
+function isTriageRescueCandidate(request: Session['requests'][number]): boolean {
+  if (request.resourceType !== 'XHR' && request.resourceType !== 'Fetch') return false;
+  return !isTelemetryRequest(request);
+}
+
+function isNearActionEvent(timestamp: number, actionTimestamps: number[]): boolean {
+  return actionTimestamps.some(
+    (eventTimestamp) =>
+      timestamp >= eventTimestamp - TRIAGE_ACTION_ALIGNMENT_BEFORE_MS &&
+      timestamp <= eventTimestamp + TRIAGE_ACTION_ALIGNMENT_AFTER_MS,
+  );
+}
+
 function triageRequestGroupKey(request: TriageRequestContext): unknown[] {
   let urlKey: string = request.url;
   let paramSignature = '';

package/src/imprint/teach.ts

@@ -27,6 +27,7 @@ import {
   type CompileAgentProgress,
   type TriageResult,
   compilePlaybook,
+  findCredentialBearingSeqs,
   generate,
   triageRequests,
 } from './compile.ts';
@@ -826,11 +827,25 @@ export async function teach(opts: TeachOptions): Promise<TeachResult> {
           const model = await getModel();
           mp.pause();
           mp.clear();
+          const credentialSeqs = findCredentialBearingSeqs(triageSession);
           spinner.start('Triaging requests');
-          localTriageResult = await triageRequests(triageSession, {
-            provider: providerName,
-            model,
-          });
+          localTriageResult = await triageRequests(
+            triageSession,
+            {
+              provider: providerName,
+              model,
+            },
+            credentialSeqs.length > 0
+              ? {
+                  sharedContext: {
+                    loginRequestSeqs: credentialSeqs,
+                    credentialNames: [],
+                    tokenExtractionNotes: '',
+                    sharedHelperNotes: '',
+                  },
+                }
+              : {},
+          );
           spinner.stop(
             `Triaged to ${localTriageResult.selectedSeqs.length} requests (from ${triageSession.requests.length}).`,
           );
@@ -868,6 +883,7 @@ export async function teach(opts: TeachOptions): Promise<TeachResult> {
           sessionPath: compileSessionPath,
           providerName,
           model,
+          trustSessionScope: !!localTriagedPath,
         });
         spinner.stop(
           `Detected ${detection.candidates.length} candidate tool${detection.candidates.length === 1 ? '' : 's'}.`,
@@ -1288,6 +1304,7 @@ async function detectTeachCandidates(opts: {
   sessionPath: string;
   providerName: ProviderName;
   model?: string;
+  trustSessionScope?: boolean;
 }): Promise<Awaited<ReturnType<typeof detectToolCandidates>>> {
   const session = loadJsonFile(
     opts.sessionPath,
@@ -1298,7 +1315,11 @@ async function detectTeachCandidates(opts: {
     },
     'session',
   );
-  return await detectToolCandidates(session, { provider: opts.providerName, model: opts.model });
+  return await detectToolCandidates(
+    session,
+    { provider: opts.providerName, model: opts.model },
+    { trustSessionScope: opts.trustSessionScope },
+  );
 }
 
 async function selectTeachCandidates(

package/src/imprint/telemetry.ts

@@ -0,0 +1,46 @@
+interface TelemetryRequestLike {
+  method: string;
+  url: string;
+  body?: string;
+  response?: {
+    body?: string;
+  };
+}
+
+const HARD_TELEMETRY_PATH_PATTERN =
+  /\/(log|gen_204|jserror|ping|beacon|csi|batchlog|metrics|stats|collect|analytics|adsct|pagead|ccm)(?=$|[/?])/i;
+const TERMINAL_EVENT_PATH_PATTERN = /\/events?\/?$/i;
+const EVENT_COLLECTOR_BODY_PATTERNS = [
+  /"app_(?:version|build)"/i,
+  /"browser_(?:name|version)"/i,
+  /"device_(?:environment|locale|make|model)"/i,
+  /"event_(?:id|name|type)"/i,
+  /"os(?:_version)?"/i,
+  /"screen_(?:height|scale_factor|width)"/i,
+];
+
+function isTelemetryPath(pathname: string): boolean {
+  return HARD_TELEMETRY_PATH_PATTERN.test(pathname);
+}
+
+export function isTelemetryRequest(request: TelemetryRequestLike): boolean {
+  let url: URL;
+  try {
+    url = new URL(request.url);
+  } catch {
+    return false;
+  }
+
+  if (isTelemetryPath(url.pathname)) return true;
+  if (!TERMINAL_EVENT_PATH_PATTERN.test(url.pathname)) return false;
+  if (request.method.toUpperCase() !== 'POST') return false;
+  if (!hasEmptyResponse(request)) return false;
+
+  const body = request.body ?? '';
+  return EVENT_COLLECTOR_BODY_PATTERNS.filter((pattern) => pattern.test(body)).length >= 2;
+}
+
+function hasEmptyResponse(request: TelemetryRequestLike): boolean {
+  const body = request.response?.body;
+  return body === undefined || body.trim().length === 0;
+}

package/src/imprint/tool-candidates.ts

@@ -14,6 +14,7 @@ import { isSameRegistrableDomain, registrableDomain } from './etld.ts';
 import { type LLMOptions, extractJsonObject, resolveProvider } from './llm.ts';
 import { createLog } from './log.ts';
 import { compactRequestContexts, requestContextDigest } from './request-context.ts';
+import { isTelemetryRequest } from './telemetry.ts';
 import { setSpanAttributes, traced } from './tracing.ts';
 import type { CapturedRequest, Session } from './types.ts';
 
@@ -120,9 +121,10 @@ export type ToolCandidate = z.infer<typeof ToolCandidateSchema>;
 const ToolCandidateDetectionSchema = z
   .object({
     sharedContext: SharedCompileContextSchema.default({}),
-    candidates: z.array(ToolCandidateSchema).min(1),
+    candidates: z.array(ToolCandidateSchema),
   })
   .superRefine((value, ctx) => {
+    if (value.candidates.length === 0) return;
     const primaryCount = value.candidates.filter((c) => c.primary).length;
     if (primaryCount !== 1) {
       ctx.addIssue({
@@ -151,9 +153,19 @@ interface DetectToolCandidatesResult extends ToolCandidateDetection {
   durationMs: number;
 }
 
+interface DetectToolCandidatesOptions {
+  /**
+   * The input session has already been reduced by request triage. Trust that
+   * selected XHR/Fetch scope instead of re-applying the raw-session origin
+   * heuristic, which would drop public cross-origin APIs such as api.remitly.io.
+   */
+  trustSessionScope?: boolean;
+}
+
 export async function detectToolCandidates(
   session: Session,
   llmConfig?: LLMOptions,
+  opts: DetectToolCandidatesOptions = {},
 ): Promise<DetectToolCandidatesResult> {
   return await traced(
     'teach.detect_tool_candidates',
@@ -171,13 +183,25 @@ export async function detectToolCandidates(
         );
       }
       const systemPrompt = readFileSync(promptPath, 'utf8');
-      const payload = buildToolCandidatePayload(session);
+      const payload = buildToolCandidatePayload(session, {
+        trustSessionScope: opts.trustSessionScope,
+      });
 
       setSpanAttributes(span, {
         'imprint.events_considered': payload.events.length,
         'imprint.requests_considered': payload.requests.length,
       });
 
+      if (payload.requests.length === 0) {
+        throw new Error(
+          [
+            'Candidate detection received no eligible XHR/Fetch requests.',
+            'Imprint needs at least one data-bearing request to compile a tool.',
+            'This usually means triage removed the load-bearing API call, the recording only captured page/static traffic, or the workflow uses a browser-local calculation with no backend request.',
+          ].join('\n'),
+        );
+      }
+
       log(
         `detecting candidate tools from ${payload.events.length} event(s), ${payload.requests.length} request(s)…`,
       );
@@ -250,6 +274,14 @@ export async function detectToolCandidates(
 export function validateToolCandidateDetection(input: unknown): ToolCandidateDetection {
   const raw = ToolCandidateDetectionSchema.parse(input);
   const before = raw.candidates.length;
+  if (before === 0) {
+    throw new Error(
+      [
+        'Candidate detector did not identify any tool candidates backed by requests.',
+        'Imprint needs at least one candidate with requestSeqs so the compiler has an API call to replay.',
+      ].join('\n'),
+    );
+  }
   raw.candidates = raw.candidates.filter((c) => c.requestSeqs.length > 0);
   if (raw.candidates.length === 0) {
     throw new Error(
@@ -316,12 +348,19 @@ interface ToolCandidatePayload {
   requests: CandidateRequestPayload[];
 }
 
-export function buildToolCandidatePayload(session: Session): ToolCandidatePayload {
+export function buildToolCandidatePayload(
+  session: Session,
+  opts: DetectToolCandidatesOptions = {},
+): ToolCandidatePayload {
   const startRoot = candidateStartRoot(session);
   const appApiHosts = inferAppApiHosts(session, startRoot);
   const requests = compactRequestContexts(
     session.requests
-      .filter((request) => isCandidateRequest(request, startRoot, appApiHosts))
+      .filter((request) =>
+        isCandidateRequest(request, startRoot, appApiHosts, {
+          trustSessionScope: opts.trustSessionScope,
+        }),
+      )
       .map((request) => {
         const body = truncate(request.body, BODY_LIMIT);
         const responsePreview = truncate(request.response?.body, RESPONSE_PREVIEW_LIMIT);
@@ -408,9 +447,6 @@ function candidateRequestGroupKey(request: CandidateRequestPayload): unknown[] {
  *  and — worse — the detector can anchor a candidate's `requestSeqs` on one
  *  (e.g. Google's `/log`), sending compile to reverse-engineer a beacon. Excluded
  *  entirely. The boundary lookahead keeps `/login`, `/catalog`, etc. safe. */
-const TELEMETRY_PATH =
-  /\/(log|gen_204|jserror|ping|beacon|csi|batchlog|metrics|stats|collect|analytics|adsct|pagead|ccm)(?=$|[/?])/i;
-
 /** Count distinct endpoint families (batchexecute rpcid, else METHOD+path) that
  *  carry a non-trivial number of requests. ≥2 means the session genuinely hit
  *  multiple backends — a single detected candidate there signals under-
@@ -433,11 +469,13 @@ function isCandidateRequest(
   request: CapturedRequest,
   startRoot: string | null,
   appApiHosts: Set<string>,
+  opts: DetectToolCandidatesOptions = {},
 ): boolean {
   if (request.resourceType !== 'XHR' && request.resourceType !== 'Fetch') return false;
   const url = safeUrl(request.url);
   if (!url) return false;
-  if (TELEMETRY_PATH.test(url.pathname)) return false;
+  if (isTelemetryRequest(request)) return false;
+  if (opts.trustSessionScope) return true;
   if (startRoot && !isSameRegistrableDomain(url.hostname, startRoot)) {
     return appApiHosts.has(url.hostname);
   }