imprint-mcp 0.6.0 → 0.6.2

package/src/imprint/tool-candidates.ts

@@ -18,7 +18,6 @@ import { createLog } from './log.ts';
 import { compactRequestContexts, requestContextDigest } from './request-context.ts';
 import { isTelemetryRequest } from './telemetry.ts';
 import { setSpanAttributes, traced } from './tracing.ts';
-import { TwoFactorTypeSchema } from './types.ts';
 import type { CapturedRequest, Session } from './types.ts';
 
 const PROMPTS_DIR = pathJoin(import.meta.dir, '..', '..', 'prompts');
@@ -97,14 +96,8 @@ export const SharedCompileContextSchema = z.object({
   credentialNames: z.array(z.string()).default([]),
   tokenExtractionNotes: z.string().default(''),
   sharedHelperNotes: z.string().default(''),
-  twoFactorDetected: z.boolean().default(false),
-  twoFactorType: TwoFactorTypeSchema,
-  twoFactorRequestSeqs: z.array(z.number().int().nonnegative()).default([]),
-  authCompletionSeqs: z.array(z.number().int().nonnegative()).default([]),
-  /** OTP only: names of initiate-response fields the completion request reads
-   *  (chained as ${state.X}); listed structurally from the recording. */
-  twoFactorContext: z.array(z.string()).default([]),
-  twoFactorNotes: z.string().default(''),
+  authRequestSeqs: z.array(z.number().int().nonnegative()).default([]),
+  authNotes: z.string().default(''),
 });
 export type SharedCompileContext = z.infer<typeof SharedCompileContextSchema>;
 
@@ -115,7 +108,11 @@ export type SharedCompileContext = z.infer<typeof SharedCompileContextSchema>;
  *  replaying the login inline (which hammers the site at compile time). */
 export function sharedContextHasAuth(ctx: SharedCompileContext | undefined): boolean {
   if (!ctx) return false;
-  return ctx.twoFactorDetected || ctx.loginRequestSeqs.length > 0 || ctx.credentialNames.length > 0;
+  return (
+    ctx.authRequestSeqs.length > 0 ||
+    ctx.loginRequestSeqs.length > 0 ||
+    ctx.credentialNames.length > 0
+  );
 }
 
 export const ToolCandidateSchema = z.object({
@@ -338,6 +335,7 @@ export function buildSharedCompileContext(
   return {
     ...detection.sharedContext,
     loginRequestSeqs: [...new Set(detection.sharedContext.loginRequestSeqs)].sort((a, b) => a - b),
+    authRequestSeqs: [...new Set(detection.sharedContext.authRequestSeqs)].sort((a, b) => a - b),
   };
 }
 

package/src/imprint/tool-loader.ts

@@ -161,9 +161,12 @@ export function toCamelCase(snake: string): string {
     .join('');
 }
 
-/** Zod validator from workflow parameters — enforces the same contract
- *  for MCP args (from the LLM) and cron.json params. */
-export function buildZodValidator(parameters: WorkflowParameter[]): z.ZodObject<z.ZodRawShape> {
+/** Zod validator from workflow parameters. Auth actions select their own
+ * required subset at runtime, so the MCP transport accepts omitted fields. */
+export function buildZodValidator(
+  parameters: WorkflowParameter[],
+  options: { allOptional?: boolean } = {},
+): z.ZodObject<z.ZodRawShape> {
   const shape: z.ZodRawShape = {};
   for (const p of parameters) {
     let field: z.ZodType;
@@ -178,8 +181,13 @@ export function buildZodValidator(parameters: WorkflowParameter[]): z.ZodObject<
         field = z.boolean();
         break;
     }
+    if (p.choices?.length) {
+      field = field.refine((value) => p.choices?.includes(value), {
+        message: `Expected one of: ${p.choices.join(', ')}`,
+      });
+    }
     field = field.describe(p.description);
-    if (p.default !== undefined) field = field.optional();
+    if (p.default !== undefined || options.allOptional) field = field.optional();
     shape[p.name] = field;
   }
   return z.object(shape);

package/src/imprint/types.ts

@@ -111,6 +111,8 @@ const WorkflowParameterSchema = z.object({
   name: z.string(),
   type: z.enum(['string', 'number', 'boolean']),
   description: z.string(),
+  /** Optional finite choices to surface as JSON Schema enum values. */
+  choices: z.array(z.union([z.string(), z.number(), z.boolean()])).optional(),
   /** Optional with this default if set. */
   default: z.union([z.string(), z.number(), z.boolean()]).optional(),
   /** Whether a `param:<name>` integration test verified this parameter's effect
@@ -152,6 +154,13 @@ const CaptureCommonSchema = z.object({
   capability: StateCapabilitySchema.optional().default('ordinary_http'),
 });
 
+const CaptureEqualsSchema = z.union([z.string(), z.number(), z.boolean(), z.null()]);
+const RequestCaptureCommonSchema = CaptureCommonSchema.extend({
+  /** Optional exact scalar match. This also makes an explicitly matched empty
+   *  string or null a valid capture value. */
+  equals: CaptureEqualsSchema.optional(),
+});
+
 const CookieCaptureSchema = CaptureCommonSchema.extend({
   source: z.literal('cookie'),
   cookie: z.string(),
@@ -162,22 +171,22 @@ const CookieCaptureSchema = CaptureCommonSchema.extend({
   allowHttpOnlyProjection: z.boolean().optional().default(false),
 });
 
-const RequestCaptureSchema = z.discriminatedUnion('source', [
-  CaptureCommonSchema.extend({
+export const RequestCaptureSchema = z.discriminatedUnion('source', [
+  RequestCaptureCommonSchema.extend({
     source: z.literal('json'),
     path: z.string(),
   }),
-  CaptureCommonSchema.extend({
+  RequestCaptureCommonSchema.extend({
     source: z.literal('response_header'),
     header: z.string(),
     mode: z.enum(['first', 'last', 'all']).optional().default('last'),
   }),
-  CaptureCommonSchema.extend({
+  RequestCaptureCommonSchema.extend({
     source: z.literal('text_regex'),
     pattern: z.string(),
     group: z.number().int().nonnegative().optional().default(1),
   }),
-  CookieCaptureSchema,
+  CookieCaptureSchema.extend({ equals: CaptureEqualsSchema.optional() }),
 ]);
 export type RequestCapture = z.infer<typeof RequestCaptureSchema>;
 
@@ -226,11 +235,59 @@ export type BootstrapCapture = z.infer<typeof BootstrapCaptureSchema>;
 
 const WorkflowRequestSchema = z.object({
   method: z.string(),
+  /** Sequence number of the captured request that grounds this workflow request.
+   *  Auth login uses this to resolve persisted captures only against their
+   *  producing recorded response. */
+  recordingRequestSeq: z.number().int().nonnegative().optional(),
   /** Template; ${param.X} substitutes a parameter, ${response[N].path} an
    *  earlier extracted value. */
   url: z.string(),
   headers: z.record(z.string()),
   body: z.string().optional(),
+  /** Execute this GET or URL-encoded POST as a top-level browser navigation instead of fetch().
+   *  This lets the recorded page run its own JavaScript and mint coupled browser
+   *  state, and lets form POSTs retain document-navigation semantics, without
+   *  teaching Imprint site- or framework-specific behavior. */
+  mode: z.enum(['fetch', 'navigate']).optional(),
+  /** Bounded completion criteria for mode="navigate". Predicates are ANDed.
+   *  With no predicate, navigation completes at the selected lifecycle event. */
+  navigation: z
+    .object({
+      waitUntil: z.enum(['domcontentloaded', 'load']).optional(),
+      timeoutMs: z.number().int().positive().optional(),
+      pollIntervalMs: z.number().int().positive().optional(),
+      urlIncludes: z.string().min(1).optional(),
+      /** Wait until the rendered document contains this CSS selector before
+       * snapshotting outerHTML. Useful for pages whose meaningful results
+       * hydrate after the load event. */
+      selector: z.string().min(1).optional(),
+      /** Optional browser interactions performed after the initial navigation
+       * predicate is satisfied. This is a generic escape hatch for workflows
+       * whose next request is assembled from private in-page state rather than
+       * values serialized into HTML. */
+      actions: z
+        .array(
+          z
+            .object({
+              action: z.literal('click'),
+              selector: z.string().min(1),
+            })
+            .strict(),
+        )
+        .min(1)
+        .optional(),
+      /** After navigation actions run, wait for this rendered selector before
+       * snapshotting the final document. */
+      resultSelector: z.string().min(1).optional(),
+      cookie: z
+        .object({
+          name: z.string().min(1),
+          domain: z.string().min(1).optional(),
+          path: z.string().min(1).optional(),
+        })
+        .optional(),
+    })
+    .optional(),
   /** Names → jsonpath expressions; later requests reference via ${response[N].name}. */
   extract: z.record(z.string()).optional(),
   captures: z.array(RequestCaptureSchema).optional(),
@@ -244,44 +301,56 @@ const WorkflowRequestSchema = z.object({
 });
 export type WorkflowRequest = z.infer<typeof WorkflowRequestSchema>;
 
-/** The two *structural* 2FA cases the runtime actually branches on, plus `none`.
- *  A code that arrives out-of-band (sms / email / authenticator app) and is typed
- *  back into a second request is one case (`otp`); an approval the user taps
- *  elsewhere while we poll is the other (`push`). The delivery *channel* never
- *  changes how we replay it, so we don't model it. */
-export const TwoFactorTypeSchema = z.enum(['otp', 'push', 'none']).default('none');
-
 const AuthConfigSchema = z
   .object({
-    twoFactorType: TwoFactorTypeSchema,
-    /** How many requests to execute for the 'initiate' phase (login + 2FA trigger).
-     *  The remaining requests run during the 'complete'/'submit_otp' phase. */
-    initiateRequestCount: z.number().int().nonnegative().default(0),
-    pollEndpoint: z.string().optional(),
-    /** Push only: HTTP method for the poll request (default POST). */
-    pollMethod: z.string().optional(),
-    /** Push only: the request body to send on each poll attempt, templated like
-     *  any other request body (`${param.X}` / `${state.X}` / `${credential.X}`).
-     *  Some poll/status endpoints reject an empty body (e.g. require a JSON
-     *  `{mfaId,...}` payload), so the compile agent must declare the recorded
-     *  poll body here — otherwise the poll silently sends nothing and the
-     *  approved push is never recognized. Omitted → body-less poll (legacy). */
-    pollBody: z.string().optional(),
-    /** Push only: Content-Type for the poll body (default application/json when
-     *  pollBody is set). Grounded in the recorded poll request's header. */
-    pollContentType: z.string().optional(),
-    pollIntervalMs: z.number().int().positive().default(3000),
-    maxPollAttempts: z.number().int().positive().default(60),
-    /** Push only: a recording-grounded capture that resolves on the *approved*
-     *  poll response (and not on the pending ones). When it yields a non-empty
-     *  value the poll is done. Omitted → fall back to "a session Set-Cookie
-     *  appeared". Replaces hardcoded body-substring matching. */
-    pollTerminal: RequestCaptureSchema.optional(),
-    /** OTP only: the names of `${state.X}` values captured from the initiate
-     *  response that the completion (submit_otp) requests need (e.g. a reauth
-     *  `mfaId`). Because each MCP call is stateless, these are echoed back to
-     *  the caller in the AWAITING_2FA result and passed in again on submit_otp. */
-    twoFactorContext: z.array(z.string()).default([]),
+    /** Recording-grounded auth program. Action names, boundaries, evidence,
+     *  retry behavior, and completion are chosen by the compile agent. */
+    entry: z.string().min(1),
+    actions: z.record(
+      z.string().min(1),
+      z
+        .object({
+          parameters: z.array(z.string().min(1)).optional().default([]),
+          steps: z
+            .array(
+              z
+                .object({
+                  request: z.number().int().nonnegative(),
+                  onError: z.enum(['fail', 'continue', 'retry']).optional().default('fail'),
+                  repeat: z
+                    .object({
+                      until: RequestCaptureSchema,
+                      intervalMs: z.number().int().nonnegative(),
+                      maxAttempts: z.number().int().positive(),
+                    })
+                    .strict()
+                    .optional(),
+                })
+                .strict(),
+            )
+            .min(1),
+          outcome: z.discriminatedUnion('type', [
+            z
+              .object({
+                type: z.literal('pause'),
+                next: z.string().min(1),
+                evidence: z.array(z.string().min(1)).optional().default([]),
+                carry: z.array(z.string().min(1)).optional().default([]),
+                message: z.string().min(1),
+              })
+              .strict(),
+            z
+              .object({
+                type: z.literal('success'),
+                evidence: z.array(z.string().min(1)).optional().default([]),
+              })
+              .strict(),
+          ]),
+        })
+        .strict(),
+    ),
+    /** Captured state names to store as durable credentials after success. */
+    persist: z.array(z.string().min(1)).optional().default([]),
     /** Opt-in: when the recorded login carries its session through a CROSS-ORIGIN
      *  `Set-Cookie` (e.g. a `functions.*`/`global.*` host sets a cookie that a
      *  later leg depends on), set this so cdp-replay writes those cross-origin
@@ -289,15 +358,8 @@ const AuthConfigSchema = z
      *  when the recording actually shows cross-origin cookie chaining; otherwise
      *  the browser's normal same-origin jar is left untouched. */
     crossOriginCookieReinjection: z.boolean().default(false),
-    /** Durable session tokens to persist after a SUCCESSFUL login completion so
-     *  DATA tools can reuse them without re-running auth (they re-auth only on
-     *  expiry / AUTH_EXPIRED). Cookies persist automatically; declare here only
-     *  the NON-cookie material a data request needs — a bearer / access / CSRF
-     *  token the completion response returns in its body or a header. Each
-     *  capture's resolved value is stored as a durable credential secret
-     *  (`${credential.NAME}`). Grounded in the recording; channel/site-agnostic. */
-    sessionCapture: z.array(RequestCaptureSchema).default([]),
   })
+  .strict()
   .optional();
 export type AuthConfig = z.infer<typeof AuthConfigSchema>;
 
@@ -331,14 +393,30 @@ export const WorkflowSchema = z.object({
    *
    *  Return value:
    *  - `string` — the transformed URL (backward-compatible).
-   *  - `{ url: string; body?: string; headers?: Record<string, string> }` —
+   *  - `{ url?: string; body?: string; headers?: Record<string, string>; navigation?: object; skip?: boolean }` —
    *    URL plus optional body and header overrides for complex body formats
    *    (JSPB, nested JSON-in-form) where placeholder substitution alone
-   *    cannot handle the encoding.
+   *    cannot handle the encoding. `navigation` may supply dynamic browser
+   *    navigation actions derived from resolved parameters. `skip: true` skips this request, for
+   *    conditional follow-up requests such as pagination/detail calls.
    *
    *  The optional 4th arg `params` carries the resolved workflow parameters
    *  so the transform can construct request bodies programmatically. */
   requestTransformModule: z.string().optional(),
+  /** Agent-authored capability limitations retained with the generated tool.
+   * A compiler may deliberately omit a secondary feature or parameter when the
+   * recording and live evidence cannot support it without guessing. Runtime
+   * execution does not interpret these notes; MCP descriptions and teach
+   * summaries surface them to callers and operators. */
+  limitations: z
+    .array(
+      z.object({
+        feature: z.string().min(1),
+        reason: z.string().min(1),
+        omittedParameters: z.array(z.string().min(1)).optional(),
+      }),
+    )
+    .optional(),
   /** Did this tool's integration test produce live data at compile time?
    *
    *  - `liveVerified: true` (default when present) — the integration test
@@ -383,12 +461,12 @@ export interface StateMissingItem {
 
 /** Discriminated union returned by every generated tool. */
 export type ToolResult<T = unknown> =
-  | { ok: true; data: T; loginResponsePreview?: string }
+  | { ok: true; data: T }
   | {
       ok: false;
       error:
         | 'AUTH_EXPIRED' // 401 — run `imprint login`
-        | 'AWAITING_2FA' // 2FA required — user must approve push / enter OTP
+        | 'ACTION_REQUIRED' // declared auth action completed; another action/user input is needed
         | 'FORBIDDEN' // 403 — bot detection, geo, ToS, capability mismatch
         | 'NETWORK' // fetch threw / timed out
         | 'RATE_LIMITED' // 429
@@ -402,17 +480,12 @@ export type ToolResult<T = unknown> =
        *  (absent for transport/STATE_MISSING failures). Surfaced so the auth
        *  compile agent sees the concrete code, not just a prose message. */
       status?: number;
-      /** Truncated response body of the failing request (first ~500 chars).
-       *  Lets the compile agent inspect the server's actual error payload
-       *  without re-running. Distinct from `loginResponsePreview`, which is the
-       *  *initiate* response preview on the AWAITING_2FA path. */
+      /** Truncated response body of the failing request (first ~500 chars). */
       responseBodyPreview?: string;
-      twoFactorType?: string;
-      /** OTP only: the `${state.X}` values captured from the initiate response
-       *  that the caller must echo back on the submit_otp call (stateless
-       *  state-chain bridge). Names are declared in authConfig.twoFactorContext. */
-      twoFactorContext?: Record<string, unknown>;
-      loginResponsePreview?: string;
+      /** Recording-derived state and generic action progress. Echo this object
+       *  unchanged on the next auth call. */
+      continuation?: Record<string, unknown>;
+      nextAction?: string;
     };
 
 // ─── Cron config (input to `imprint cron`) ───────────────────────────────────
@@ -610,11 +683,7 @@ const PlaybookResultSchema = z.discriminatedUnion('source', [
 ]);
 export type PlaybookResult = z.infer<typeof PlaybookResultSchema>;
 
-/** A named value extracted from a captured XHR response, in addition to the
- *  success marker. Used by a login playbook to carry a 2FA-chain token (e.g. a
- *  single-use `SecurityCode` minted in the browser during the OTP-send step)
- *  out of the playbook run so a later stateless `submit_otp` can include it.
- *  The `name` should match an `authConfig.twoFactorContext` entry. */
+/** A named value extracted from a playbook's captured XHR response. */
 const PlaybookCaptureSchema = z.object({
   name: z.string(),
   /** Regex matched against the captured response URL. */