imprint-mcp 0.2.0

package/src/imprint/tool-candidates.ts

@@ -0,0 +1,423 @@
+/**
+ * Candidate-tool detection for `imprint teach`.
+ *
+ * One browser recording can exercise multiple user-facing intents. This pass
+ * runs after redaction and before compile so teach can fan out the shared
+ * session into one generated tool per selected candidate.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join as pathJoin } from 'node:path';
+import { z } from 'zod';
+import { inferAppApiHosts } from './app-api-hosts.ts';
+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 { setSpanAttributes, traced } from './tracing.ts';
+import type { CapturedRequest, Session } from './types.ts';
+
+const PROMPTS_DIR = pathJoin(import.meta.dir, '..', '..', 'prompts');
+const BODY_LIMIT = 800;
+const RESPONSE_PREVIEW_LIMIT = 500;
+const HEADER_LIMIT = 600;
+const log = createLog('candidates');
+
+function normalizeCandidateParamType(value: unknown): unknown {
+  if (typeof value !== 'string') {
+    return value;
+  }
+
+  const normalized = value
+    .trim()
+    .toLowerCase()
+    .replace(/[\s_-]+/g, '');
+  if (normalized.length === 0) {
+    return undefined;
+  }
+
+  if (
+    normalized === 'string' ||
+    normalized === 'str' ||
+    normalized === 'text' ||
+    normalized === 'array' ||
+    normalized === 'list' ||
+    normalized === 'string[]' ||
+    normalized === 'array<string>' ||
+    normalized === 'stringarray' ||
+    normalized === 'stringlist'
+  ) {
+    return 'string';
+  }
+
+  if (
+    normalized === 'number' ||
+    normalized === 'integer' ||
+    normalized === 'int' ||
+    normalized === 'float' ||
+    normalized === 'numeric' ||
+    normalized === 'number[]' ||
+    normalized === 'array<number>' ||
+    normalized === 'numberarray' ||
+    normalized === 'numberlist'
+  ) {
+    return 'number';
+  }
+
+  if (
+    normalized === 'boolean' ||
+    normalized === 'bool' ||
+    normalized === 'boolean[]' ||
+    normalized === 'bool[]' ||
+    normalized === 'array<boolean>' ||
+    normalized === 'booleanarray' ||
+    normalized === 'booleanlist'
+  ) {
+    return 'boolean';
+  }
+
+  return undefined;
+}
+
+const CandidateParamSchema = z.object({
+  name: z.string(),
+  type: z.preprocess(
+    normalizeCandidateParamType,
+    z.enum(['string', 'number', 'boolean']).optional(),
+  ),
+  description: z.string().optional(),
+});
+
+export const SharedCompileContextSchema = z.object({
+  loginRequestSeqs: z.array(z.number().int().nonnegative()).default([]),
+  credentialNames: z.array(z.string()).default([]),
+  tokenExtractionNotes: z.string().default(''),
+  sharedHelperNotes: z.string().default(''),
+});
+export type SharedCompileContext = z.infer<typeof SharedCompileContextSchema>;
+
+export const ToolCandidateSchema = z.object({
+  toolName: z.string().regex(/^[a-z][a-z0-9_]*$/),
+  description: z.string().min(1),
+  rationale: z.string().min(1),
+  confidence: z.number().min(0).max(1),
+  primary: z.boolean(),
+  requestSeqs: z.array(z.number().int().nonnegative()).default([]),
+  representativeSeqs: z.array(z.number().int().nonnegative()).default([]),
+  eventSeqs: z.array(z.number().int().nonnegative()).default([]),
+  eventTimeRange: z
+    .object({
+      startTimestamp: z.number(),
+      endTimestamp: z.number(),
+    })
+    .optional(),
+  expectedOutput: z.string().default(''),
+  likelyParams: z.array(CandidateParamSchema).default([]),
+  dependencySeqs: z.array(z.number().int().nonnegative()).default([]),
+});
+export type ToolCandidate = z.infer<typeof ToolCandidateSchema>;
+
+const ToolCandidateDetectionSchema = z
+  .object({
+    sharedContext: SharedCompileContextSchema.default({}),
+    candidates: z.array(ToolCandidateSchema).min(1),
+  })
+  .superRefine((value, ctx) => {
+    const primaryCount = value.candidates.filter((c) => c.primary).length;
+    if (primaryCount !== 1) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['candidates'],
+        message: `expected exactly one primary candidate, got ${primaryCount}`,
+      });
+    }
+    const names = new Set<string>();
+    for (const [i, candidate] of value.candidates.entries()) {
+      if (names.has(candidate.toolName)) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ['candidates', i, 'toolName'],
+          message: `duplicate toolName "${candidate.toolName}"`,
+        });
+      }
+      names.add(candidate.toolName);
+    }
+  });
+type ToolCandidateDetection = z.infer<typeof ToolCandidateDetectionSchema>;
+
+interface DetectToolCandidatesResult extends ToolCandidateDetection {
+  inputTokens: number | null;
+  outputTokens: number | null;
+  durationMs: number;
+}
+
+export async function detectToolCandidates(
+  session: Session,
+  llmConfig?: LLMOptions,
+): Promise<DetectToolCandidatesResult> {
+  return await traced(
+    'teach.detect_tool_candidates',
+    'AGENT',
+    {
+      'imprint.site': session.site,
+      'imprint.session_url': session.url,
+      'imprint.provider': llmConfig?.provider ?? 'auto',
+    },
+    async (span) => {
+      const promptPath = pathJoin(PROMPTS_DIR, 'tool-candidate-detection.md');
+      if (!existsSync(promptPath)) {
+        throw new Error(
+          `Candidate detection prompt not found at ${promptPath}\n→ this is an Imprint installation problem.`,
+        );
+      }
+      const systemPrompt = readFileSync(promptPath, 'utf8');
+      const payload = buildToolCandidatePayload(session);
+
+      setSpanAttributes(span, {
+        'imprint.events_considered': payload.events.length,
+        'imprint.requests_considered': payload.requests.length,
+      });
+
+      log(
+        `detecting candidate tools from ${payload.events.length} event(s), ${payload.requests.length} request(s)…`,
+      );
+      const llm = resolveProvider(llmConfig ?? {});
+      const result = await llm.analyze(systemPrompt, payload);
+      const objectText = extractJsonObject(result.text);
+      if (!objectText) {
+        throw new Error(
+          `Candidate detector did not return a JSON object.\nRaw response:\n${result.text.slice(0, 1000)}`,
+        );
+      }
+
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(objectText);
+      } catch (err) {
+        throw new Error(
+          `Candidate detector response was not valid JSON: ${err instanceof Error ? err.message : String(err)}\nExtracted:\n${objectText.slice(0, 1000)}`,
+        );
+      }
+
+      const detection = validateToolCandidateDetection(parsed);
+      setSpanAttributes(span, {
+        'imprint.candidate_count': detection.candidates.length,
+        'imprint.primary_tool_name': detection.candidates.find((c) => c.primary)?.toolName,
+        'imprint.detect.duration_ms': result.durationMs,
+        'imprint.detect.input_tokens': result.inputTokens,
+        'imprint.detect.output_tokens': result.outputTokens,
+      });
+      return {
+        ...detection,
+        inputTokens: result.inputTokens,
+        outputTokens: result.outputTokens,
+        durationMs: result.durationMs,
+      };
+    },
+  );
+}
+
+export function validateToolCandidateDetection(input: unknown): ToolCandidateDetection {
+  const raw = ToolCandidateDetectionSchema.parse(input);
+  const before = raw.candidates.length;
+  raw.candidates = raw.candidates.filter((c) => c.requestSeqs.length > 0);
+  if (raw.candidates.length === 0) {
+    throw new Error(
+      `All ${before} candidate(s) had empty requestSeqs — cannot compile tools without backing requests.`,
+    );
+  }
+  if (raw.candidates.length < before) {
+    log(
+      `dropped ${before - raw.candidates.length} candidate(s) with empty requestSeqs (${raw.candidates.length} remaining)`,
+    );
+  }
+  if (!raw.candidates.some((c) => c.primary)) {
+    const first = raw.candidates[0];
+    if (first) first.primary = true;
+  }
+  return raw;
+}
+
+export function primaryToolCandidate(detection: ToolCandidateDetection): ToolCandidate {
+  const primary = detection.candidates.find((c) => c.primary);
+  if (!primary) {
+    throw new Error('candidate detection has no primary candidate');
+  }
+  return primary;
+}
+
+export function buildSharedCompileContext(
+  detection: ToolCandidateDetection,
+  _selected: ToolCandidate[],
+): SharedCompileContext {
+  return {
+    ...detection.sharedContext,
+    loginRequestSeqs: [...new Set(detection.sharedContext.loginRequestSeqs)].sort((a, b) => a - b),
+  };
+}
+
+interface CandidateRequestPayload {
+  seq: number;
+  timestamp: number;
+  method: string;
+  url: string;
+  resourceType: string;
+  status?: number;
+  mimeType?: string;
+  headers: string;
+  body?: string;
+  bodyDigest?: string;
+  bodyLength?: number;
+  responsePreview?: string;
+  responseBodyDigest?: string;
+  responseBodyLength?: number;
+  credentialPlaceholders: string[];
+  likelyLoginOrAuth: boolean;
+  repeatCount?: number;
+  repeatedSeqs?: number[];
+  lastTimestamp?: number;
+}
+
+interface ToolCandidatePayload {
+  site: string;
+  url: string;
+  narration: Array<{ seq: number; timestamp: number; text: string }>;
+  events: Array<{ seq: number; timestamp: number; type: string; detail: string }>;
+  requests: CandidateRequestPayload[];
+}
+
+export function buildToolCandidatePayload(session: Session): ToolCandidatePayload {
+  const startRoot = candidateStartRoot(session);
+  const appApiHosts = inferAppApiHosts(session, startRoot);
+  const requests = compactRequestContexts(
+    session.requests
+      .filter((request) => isCandidateRequest(request, startRoot, appApiHosts))
+      .map((request) => {
+        const body = truncate(request.body, BODY_LIMIT);
+        const responsePreview = truncate(request.response?.body, RESPONSE_PREVIEW_LIMIT);
+        const placeholderText = `${request.url}\n${JSON.stringify(request.headers)}\n${request.body ?? ''}`;
+        return {
+          seq: request.seq,
+          timestamp: request.timestamp,
+          method: request.method,
+          url: request.url,
+          resourceType: request.resourceType,
+          status: request.response?.status,
+          mimeType: request.response?.mimeType,
+          headers: truncate(JSON.stringify(request.headers), HEADER_LIMIT) ?? '{}',
+          body,
+          bodyDigest: requestContextDigest(request.body),
+          bodyLength: request.body?.length,
+          responsePreview,
+          responseBodyDigest: requestContextDigest(request.response?.body),
+          responseBodyLength: request.response?.body?.length,
+          credentialPlaceholders: credentialPlaceholders(placeholderText),
+          likelyLoginOrAuth: likelyLoginOrAuth(request),
+        };
+      }),
+    candidateRequestGroupKey,
+  );
+
+  return {
+    site: session.site,
+    url: session.url,
+    narration: session.narration.map((n) => ({
+      seq: n.seq,
+      timestamp: n.timestamp,
+      text: n.text,
+    })),
+    events: session.events.map((e) => ({
+      seq: e.seq,
+      timestamp: e.timestamp,
+      type: e.type,
+      detail: truncate(e.detail, 1000) ?? '',
+    })),
+    requests,
+  };
+}
+
+function candidateStartRoot(session: Session): string | null {
+  for (const value of [
+    session.url,
+    ...session.events.filter((event) => event.type === 'navigation').map((event) => event.detail),
+    ...session.requests
+      .filter((request) => request.resourceType === 'Document')
+      .map((request) => request.url),
+  ]) {
+    const root = rootFromHttpUrl(value);
+    if (root) return root;
+  }
+  return null;
+}
+
+function rootFromHttpUrl(value: string): string | null {
+  const url = safeUrl(value);
+  if (!url || !url.hostname) return null;
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') return null;
+  return registrableDomain(url.hostname) || null;
+}
+
+function candidateRequestGroupKey(request: CandidateRequestPayload): unknown[] {
+  return [
+    request.method,
+    request.url,
+    request.bodyDigest,
+    request.bodyLength,
+    request.status,
+    request.mimeType,
+    request.responseBodyDigest,
+    request.responseBodyLength,
+    request.credentialPlaceholders,
+    request.likelyLoginOrAuth,
+  ];
+}
+
+function isCandidateRequest(
+  request: CapturedRequest,
+  startRoot: string | null,
+  appApiHosts: Set<string>,
+): boolean {
+  if (request.resourceType !== 'XHR' && request.resourceType !== 'Fetch') return false;
+  const url = safeUrl(request.url);
+  if (!url) return false;
+  if (startRoot && !isSameRegistrableDomain(url.hostname, startRoot)) {
+    return appApiHosts.has(url.hostname);
+  }
+  return true;
+}
+
+function likelyLoginOrAuth(request: CapturedRequest): boolean {
+  const url = safeUrl(request.url);
+  const endpointText =
+    `${request.method} ${url ? `${url.pathname} ${url.search}` : request.url} ${request.body ?? ''}`.toLowerCase();
+  const headerText = JSON.stringify(request.headers ?? {}).toLowerCase();
+  if (/\$\{credential\.[^}]+\}/.test(`${endpointText} ${headerText}`)) return true;
+
+  // Data requests often carry CSRF headers. Treat endpoint/body semantics as the
+  // signal so normal authenticated API calls do not get mislabeled as auth setup.
+  return /login|signin|sign-in|authenticate|authentication|oauth|session|password|csrf|token/.test(
+    endpointText,
+  );
+}
+
+function credentialPlaceholders(s: string): string[] {
+  const names = new Set<string>();
+  for (const match of s.matchAll(/\$\{credential\.([^}]+)\}/g)) {
+    if (match[1]) names.add(match[1]);
+  }
+  return [...names];
+}
+
+function truncate(s: string | undefined, limit: number): string | undefined {
+  if (!s) return undefined;
+  if (s.length <= limit) return s;
+  return `${s.slice(0, limit)}…(truncated, original length ${s.length})`;
+}
+
+function safeUrl(s: string): URL | null {
+  try {
+    return new URL(s);
+  } catch {
+    return null;
+  }
+}

package/src/imprint/tool-loader.ts

@@ -0,0 +1,186 @@
+/** Discover + load generated tools from <assetRoot>/<site>/<toolName>/index.ts. Used
+ *  by mcp-server, cron, and probe-backends. */
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { dirname, join as pathJoin, resolve as pathResolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { z } from 'zod';
+import { ensureImprintRuntimeLink } from './runtime-link.ts';
+import type { ToolResult, Workflow, WorkflowParameter } from './types.ts';
+
+type GeneratedToolFn = (
+  input: Record<string, unknown>,
+  opts?: Record<string, unknown>,
+) => Promise<ToolResult>;
+
+interface GeneratedModule {
+  WORKFLOW: Workflow;
+  [exportName: string]: unknown;
+}
+
+export interface ResolvedTool {
+  /** Directory name under the asset root, e.g. "discoverandgo". */
+  site: string;
+  /** Absolute path to the directory containing workflow.json, playbook.yaml, etc. */
+  dir: string;
+  workflow: Workflow;
+  toolFn: GeneratedToolFn;
+}
+
+/** Scan the generated asset root, dynamically import each nested tool index.ts. Per-entry
+ *  errors go to stderr and the entry is skipped — discovery never throws. */
+export async function discoverTools(
+  assetRoot: string,
+  only?: string,
+  logPrefix = '[imprint]',
+): Promise<ResolvedTool[]> {
+  if (!existsSync(assetRoot)) return [];
+  // Self-heal the node_modules/imprint symlink so generated tools' import
+  // of `imprint/runtime` resolves even when the original codegen-time
+  // repo path has moved or vanished (e.g. ephemeral Conductor workspace).
+  ensureImprintRuntimeLink(assetRoot);
+  const entries = readdirSync(assetRoot);
+  const out: ResolvedTool[] = [];
+  for (const entry of entries) {
+    if (only && entry !== only) continue;
+    const dir = pathResolve(assetRoot, entry);
+    let isDir = false;
+    try {
+      isDir = statSync(dir).isDirectory();
+    } catch {
+      continue;
+    }
+    if (!isDir) continue;
+
+    // Tool layout: <assetRoot>/<site>/<toolName>/index.ts
+    for (const sub of readdirSync(dir)) {
+      const subDir = pathResolve(dir, sub);
+      try {
+        if (!statSync(subDir).isDirectory()) continue;
+      } catch {
+        continue;
+      }
+      const subModule = pathResolve(subDir, 'index.ts');
+      if (!existsSync(subModule)) continue;
+      const tool = await tryLoadTool(subModule, entry, logPrefix);
+      if (tool) out.push(tool);
+    }
+  }
+  return out;
+}
+
+async function tryLoadTool(
+  modulePath: string,
+  site: string,
+  logPrefix: string,
+): Promise<ResolvedTool | null> {
+  let mod: GeneratedModule;
+  if (hasStaleRuntimeImport(modulePath)) {
+    await tryRepairGeneratedModule(modulePath, logPrefix);
+  }
+  try {
+    mod = (await import(modulePath)) as GeneratedModule;
+  } catch (err) {
+    if (
+      canRepairStaleRuntimeImport(err) &&
+      (await tryRepairGeneratedModule(modulePath, logPrefix))
+    ) {
+      try {
+        const repairedUrl = `${pathToFileURL(modulePath).href}?imprintRepair=${Date.now()}`;
+        mod = (await import(repairedUrl)) as GeneratedModule;
+      } catch (repairErr) {
+        process.stderr.write(
+          `${logPrefix} skipping ${modulePath}: failed to load after repair (${repairErr instanceof Error ? repairErr.message : String(repairErr)})\n`,
+        );
+        return null;
+      }
+    } else {
+      process.stderr.write(
+        `${logPrefix} skipping ${modulePath}: failed to load (${err instanceof Error ? err.message : String(err)})\n`,
+      );
+      return null;
+    }
+  }
+  if (!mod.WORKFLOW) {
+    process.stderr.write(`${logPrefix} skipping ${modulePath}: missing WORKFLOW export\n`);
+    return null;
+  }
+  const fn = findToolFunction(mod);
+  if (!fn) {
+    process.stderr.write(
+      `${logPrefix} skipping ${modulePath}: missing exported function for "${mod.WORKFLOW.toolName}"\n`,
+    );
+    return null;
+  }
+  return { site, dir: dirname(modulePath), workflow: mod.WORKFLOW, toolFn: fn };
+}
+
+function hasStaleRuntimeImport(modulePath: string): boolean {
+  try {
+    const source = readFileSync(modulePath, 'utf8');
+    return /from\s+['"][^'"]*\/src\/imprint\/runtime\.ts['"]/.test(source);
+  } catch {
+    return false;
+  }
+}
+
+function canRepairStaleRuntimeImport(err: unknown): boolean {
+  const message = err instanceof Error ? err.message : String(err);
+  return message.includes('Cannot find module') && message.includes('/src/imprint/runtime.ts');
+}
+
+async function tryRepairGeneratedModule(modulePath: string, logPrefix: string): Promise<boolean> {
+  const toolDir = dirname(modulePath);
+  const workflowPath = pathJoin(toolDir, 'workflow.json');
+  try {
+    const { emit } = await import('./emit.ts');
+    emit({ workflowPath, outDir: toolDir, force: true });
+    process.stderr.write(`${logPrefix} repaired stale generated wrapper at ${modulePath}\n`);
+    return true;
+  } catch (err) {
+    process.stderr.write(
+      `${logPrefix} could not repair stale generated wrapper at ${modulePath}: ${err instanceof Error ? err.message : String(err)}\n`,
+    );
+    return false;
+  }
+}
+
+/** Tool fn export is the camelCase of toolName: book_x_y → bookXY. */
+export function findToolFunction(mod: GeneratedModule): GeneratedToolFn | null {
+  const camelName = toCamelCase(mod.WORKFLOW.toolName);
+  const fn = mod[camelName];
+  return typeof fn === 'function' ? (fn as GeneratedToolFn) : null;
+}
+
+export function toCamelCase(snake: string): string {
+  return snake
+    .split('_')
+    .map((p, i) =>
+      i === 0 ? p.toLowerCase() : p.charAt(0).toUpperCase() + p.slice(1).toLowerCase(),
+    )
+    .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> {
+  const shape: z.ZodRawShape = {};
+  for (const p of parameters) {
+    let field: z.ZodType;
+    switch (p.type) {
+      case 'string':
+        field = z.string();
+        break;
+      case 'number':
+        field = z.number();
+        break;
+      case 'boolean':
+        field = z.boolean();
+        break;
+    }
+    field = field.describe(p.description);
+    if (p.default !== undefined) field = field.optional();
+    shape[p.name] = field;
+  }
+  return z.object(shape);
+}

package/src/imprint/tool-selection.ts

@@ -0,0 +1,70 @@
+import {
+  basename,
+  isAbsolute as pathIsAbsolute,
+  relative as pathRelative,
+  resolve as pathResolve,
+} from 'node:path';
+import type { ResolvedTool } from './tool-loader.ts';
+
+interface SelectGeneratedToolOptions {
+  site: string;
+  tools: ResolvedTool[];
+  purpose: 'cron' | 'probe';
+  toolName?: string;
+  pathHint?: string;
+  pathHintLabel?: string;
+}
+
+export function selectGeneratedTool(opts: SelectGeneratedToolOptions): ResolvedTool | null {
+  const { site, tools, purpose, toolName, pathHint, pathHintLabel } = opts;
+  if (tools.length === 0) return null;
+
+  const byName = toolName ? findToolByName(tools, toolName) : null;
+  if (toolName && !byName) {
+    throw new Error(
+      [
+        `No generated tool named "${toolName}" for site "${site}".`,
+        `Available tools: ${tools.map(displayToolName).join(', ')}`,
+      ].join('\n'),
+    );
+  }
+
+  const byPath = pathHint ? findToolByPath(tools, pathHint) : null;
+  if (byName && byPath && byName.dir !== byPath.dir) {
+    throw new Error(
+      `${pathHintLabel ?? 'path'} belongs to "${displayToolName(byPath)}", but --tool selected "${displayToolName(byName)}".`,
+    );
+  }
+  if (byName) return byName;
+  if (byPath) return byPath;
+  if (tools.length === 1) return tools[0] ?? null;
+
+  throw new Error(
+    [
+      `Site "${site}" has ${tools.length} generated tools; choose one for ${purpose}.`,
+      `Available tools:\n${tools.map((tool) => `  --tool ${displayToolName(tool)}    (${tool.dir})`).join('\n')}`,
+    ].join('\n'),
+  );
+}
+
+function findToolByName(tools: ResolvedTool[], name: string): ResolvedTool | null {
+  return (
+    tools.find((tool) => tool.workflow.toolName === name || basename(tool.dir) === name) ?? null
+  );
+}
+
+function findToolByPath(tools: ResolvedTool[], pathHint: string): ResolvedTool | null {
+  const absolutePath = pathResolve(pathHint);
+  for (const tool of tools) {
+    const dir = pathResolve(tool.dir);
+    const relative = pathRelative(dir, absolutePath);
+    if (relative === '' || (!relative.startsWith('..') && !pathIsAbsolute(relative))) {
+      return tool;
+    }
+  }
+  return null;
+}
+
+function displayToolName(tool: ResolvedTool): string {
+  return tool.workflow.toolName || basename(tool.dir);
+}