markform 0.1.0 → 0.1.1

package/dist/{src-DBD3Dt4f.mjs → src-Cs4_9lWP.mjs}

@@ -1,9 +1,11 @@
-import { $ as PatchSchema, _ as DEFAULT_PRIORITY, f as AGENT_ROLE, h as DEFAULT_MAX_TURNS, it as SessionTranscriptSchema, m as DEFAULT_MAX_PATCHES_PER_TURN, n as getFieldsForRoles, p as DEFAULT_MAX_ISSUES, r as inspect, t as applyPatches, u as serialize, v as DEFAULT_ROLE_INSTRUCTIONS } from "./apply-C0vjijlP.mjs";
+import { S as getWebSearchConfig, _ as DEFAULT_PRIORITY, at as SessionTranscriptSchema, et as PatchSchema, f as AGENT_ROLE, h as DEFAULT_MAX_TURNS, m as DEFAULT_MAX_PATCHES_PER_TURN, n as getFieldsForRoles, p as DEFAULT_MAX_ISSUES, r as inspect, t as applyPatches, u as serialize, v as DEFAULT_ROLE_INSTRUCTIONS } from "./apply-BQdd-fdx.mjs";
 import { z } from "zod";
 import Markdoc from "@markdoc/markdoc";
 import YAML from "yaml";
-import { createHash } from "node:crypto";
+import { sha256 } from "js-sha256";
 import { generateText, stepCountIs, zodSchema } from "ai";
+import { openai } from "@ai-sdk/openai";
+import { google } from "@ai-sdk/google";
 
 //#region src/engine/parse.ts
 /**
@@ -395,11 +397,17 @@ function parseCheckboxesField(node) {
 	const approvalModeStr = getStringAttr(node, "approvalMode");
 	let approvalMode = "none";
 	if (approvalModeStr === "blocking") approvalMode = "blocking";
+	const explicitRequired = getBooleanAttr(node, "required");
+	let required;
+	if (checkboxMode === "explicit") {
+		if (explicitRequired === false) throw new ParseError(`Checkbox field "${label}" has checkboxMode="explicit" which is inherently required. Cannot set required=false. Remove required attribute or change checkboxMode.`);
+		required = true;
+	} else required = explicitRequired ?? false;
 	const field = {
 		kind: "checkboxes",
 		id,
 		label,
-		required: getBooleanAttr(node, "required") ?? false,
+		required,
 		priority: getPriorityAttr(node),
 		role: getStringAttr(node, "role") ?? AGENT_ROLE,
 		checkboxMode,
@@ -423,6 +431,69 @@ function parseCheckboxesField(node) {
 	};
 }
 /**
+* Parse a url-field tag.
+*/
+function parseUrlField(node) {
+	const id = getStringAttr(node, "id");
+	const label = getStringAttr(node, "label");
+	if (!id) throw new ParseError("url-field missing required 'id' attribute");
+	if (!label) throw new ParseError(`url-field '${id}' missing required 'label' attribute`);
+	const field = {
+		kind: "url",
+		id,
+		label,
+		required: getBooleanAttr(node, "required") ?? false,
+		priority: getPriorityAttr(node),
+		role: getStringAttr(node, "role") ?? AGENT_ROLE,
+		validate: getValidateAttr(node)
+	};
+	const fenceContent = extractFenceValue(node);
+	return {
+		field,
+		value: {
+			kind: "url",
+			value: fenceContent !== null ? fenceContent.trim() : null
+		}
+	};
+}
+/**
+* Parse a url-list tag.
+*/
+function parseUrlListField(node) {
+	const id = getStringAttr(node, "id");
+	const label = getStringAttr(node, "label");
+	if (!id) throw new ParseError("url-list missing required 'id' attribute");
+	if (!label) throw new ParseError(`url-list '${id}' missing required 'label' attribute`);
+	const field = {
+		kind: "url_list",
+		id,
+		label,
+		required: getBooleanAttr(node, "required") ?? false,
+		priority: getPriorityAttr(node),
+		role: getStringAttr(node, "role") ?? AGENT_ROLE,
+		minItems: getNumberAttr(node, "minItems"),
+		maxItems: getNumberAttr(node, "maxItems"),
+		uniqueItems: getBooleanAttr(node, "uniqueItems"),
+		validate: getValidateAttr(node)
+	};
+	const fenceContent = extractFenceValue(node);
+	const items = [];
+	if (fenceContent !== null) {
+		const lines = fenceContent.split("\n");
+		for (const line of lines) {
+			const trimmed = line.trim();
+			if (trimmed) items.push(trimmed);
+		}
+	}
+	return {
+		field,
+		value: {
+			kind: "url_list",
+			items
+		}
+	};
+}
+/**
 * Parse a field tag and return field schema and value.
 */
 function parseField(node) {
@@ -434,6 +505,8 @@ function parseField(node) {
 		case "single-select": return parseSingleSelectField(node);
 		case "multi-select": return parseMultiSelectField(node);
 		case "checkboxes": return parseCheckboxesField(node);
+		case "url-field": return parseUrlField(node);
+		case "url-list": return parseUrlListField(node);
 		default: return null;
 	}
 }
@@ -579,6 +652,7 @@ function parseForm(markdown) {
 	return {
 		schema: formSchema,
 		valuesByFieldId,
+		skipsByFieldId: {},
 		docs,
 		orderIndex,
 		idIndex
@@ -960,6 +1034,75 @@ function coerceToCheckboxes(field, rawValue) {
 		}
 	};
 }
+function coerceToUrl(fieldId, rawValue) {
+	if (rawValue === null) return {
+		ok: true,
+		patch: {
+			op: "set_url",
+			fieldId,
+			value: null
+		}
+	};
+	if (typeof rawValue === "string") return {
+		ok: true,
+		patch: {
+			op: "set_url",
+			fieldId,
+			value: rawValue
+		}
+	};
+	return {
+		ok: false,
+		error: `Cannot coerce ${typeof rawValue} to url for field '${fieldId}'`
+	};
+}
+function coerceToUrlList(fieldId, rawValue) {
+	if (rawValue === null) return {
+		ok: true,
+		patch: {
+			op: "set_url_list",
+			fieldId,
+			items: []
+		}
+	};
+	if (isStringArray(rawValue)) return {
+		ok: true,
+		patch: {
+			op: "set_url_list",
+			fieldId,
+			items: rawValue
+		}
+	};
+	if (typeof rawValue === "string") return {
+		ok: true,
+		patch: {
+			op: "set_url_list",
+			fieldId,
+			items: [rawValue]
+		},
+		warning: `Coerced single string to array for field '${fieldId}'`
+	};
+	if (Array.isArray(rawValue)) {
+		const items = [];
+		for (const item of rawValue) if (typeof item === "string") items.push(item);
+		else return {
+			ok: false,
+			error: `Cannot coerce array with non-string items to url_list for field '${fieldId}'`
+		};
+		return {
+			ok: true,
+			patch: {
+				op: "set_url_list",
+				fieldId,
+				items
+			}
+		};
+	}
+	return {
+		ok: false,
+		error: `Cannot coerce ${typeof rawValue} to url_list for field '${fieldId}'`
+	};
+}
 /**
 * Coerce a raw value to a Patch for a specific field.
 */
@@ -976,10 +1119,8 @@ function coerceToFieldPatch(form, fieldId, rawValue) {
 		case "single_select": return coerceToSingleSelect(field, rawValue);
 		case "multi_select": return coerceToMultiSelect(field, rawValue);
 		case "checkboxes": return coerceToCheckboxes(field, rawValue);
-		default: return {
-			ok: false,
-			error: `Unknown field kind: ${field.kind}`
-		};
+		case "url": return coerceToUrl(fieldId, rawValue);
+		case "url_list": return coerceToUrlList(fieldId, rawValue);
 	}
 }
 /**
@@ -1062,9 +1203,18 @@ var FormHarness = class {
 	}
 	/**
 	* Check if the harness has reached max turns.
+	*
+	* Returns true when we've completed all allowed turns. This happens when:
+	* - turnNumber >= maxTurns AND we've already applied (state is "complete")
+	* - OR turnNumber > maxTurns (we've exceeded the limit)
+	*
+	* This allows the harness loop to run N times when maxTurns=N by returning
+	* false when we're at turn N but haven't applied yet (state is "wait").
 	*/
 	hasReachedMaxTurns() {
-		return this.turnNumber >= this.config.maxTurns;
+		if (this.turnNumber > this.config.maxTurns) return true;
+		if (this.turnNumber === this.config.maxTurns && this.state === "complete") return true;
+		return false;
 	}
 	/**
 	* Perform a step - inspect the form and return current state.
@@ -1093,18 +1243,9 @@ var FormHarness = class {
 		}
 		this.state = "step";
 		const result = inspect(this.form, { targetRoles: this.config.targetRoles });
-		const limitedIssues = this.filterIssuesByScope(result.issues).slice(0, this.config.maxIssues);
-		const stepBudget = Math.min(this.config.maxPatchesPerTurn, limitedIssues.filter((i) => i.severity === "required").length);
-		if (result.isComplete) this.state = "complete";
-		else this.state = "wait";
-		return {
-			structureSummary: result.structureSummary,
-			progressSummary: result.progressSummary,
-			issues: limitedIssues,
-			stepBudget,
-			isComplete: result.isComplete,
-			turnNumber: this.turnNumber
-		};
+		const stepResult = this.computeStepResult(result);
+		this.state = stepResult.issues.length === 0 ? "complete" : "wait";
+		return stepResult;
 	}
 	/**
 	* Apply patches to the form.
@@ -1114,29 +1255,27 @@ var FormHarness = class {
 	*
 	* @param patches - Patches to apply
 	* @param issues - Issues that were shown to the agent (for recording)
+	* @param llmStats - Optional LLM stats for session logging
 	* @returns StepResult after applying patches
 	*/
-	apply(patches, issues) {
+	apply(patches, issues, llmStats) {
 		if (this.state !== "wait") throw new Error(`Cannot apply in state: ${this.state}`);
 		if (patches.length > this.config.maxPatchesPerTurn) throw new Error(`Too many patches: ${patches.length} > ${this.config.maxPatchesPerTurn}`);
-		const result = applyPatches(this.form, patches);
-		const markdown = serialize(this.form);
-		const hash = createHash("sha256").update(markdown).digest("hex");
-		const requiredIssueCount = result.issues.filter((i) => i.severity === "required").length;
-		this.turns.push({
-			turn: this.turnNumber,
-			inspect: { issues },
-			apply: { patches },
-			after: {
-				requiredIssueCount,
-				markdownSha256: hash
-			}
-		});
-		const limitedIssues = this.filterIssuesByScope(result.issues).slice(0, this.config.maxIssues);
-		const stepBudget = Math.min(this.config.maxPatchesPerTurn, limitedIssues.filter((i) => i.severity === "required").length);
-		if (result.isComplete) this.state = "complete";
-		else if (this.turnNumber >= this.config.maxTurns) this.state = "complete";
+		applyPatches(this.form, patches);
+		const result = inspect(this.form, { targetRoles: this.config.targetRoles });
+		const stepResult = this.computeStepResult(result);
+		this.recordTurn(issues, patches, result, llmStats);
+		if (stepResult.issues.length === 0 || this.turnNumber >= this.config.maxTurns) this.state = "complete";
 		else this.state = "wait";
+		return stepResult;
+	}
+	/**
+	* Compute step result from inspect result.
+	* Applies issue filtering and computes step budget.
+	*/
+	computeStepResult(result) {
+		const limitedIssues = this.filterIssuesByScope(result.issues).slice(0, this.config.maxIssues);
+		const stepBudget = Math.min(this.config.maxPatchesPerTurn, limitedIssues.length);
 		return {
 			structureSummary: result.structureSummary,
 			progressSummary: result.progressSummary,
@@ -1147,6 +1286,26 @@ var FormHarness = class {
 		};
 	}
 	/**
+	* Record a turn in the session transcript.
+	*/
+	recordTurn(issues, patches, result, llmStats) {
+		const hash = sha256(serialize(this.form));
+		const requiredIssueCount = result.issues.filter((i) => i.severity === "required").length;
+		const turn = {
+			turn: this.turnNumber,
+			inspect: { issues },
+			apply: { patches },
+			after: {
+				requiredIssueCount,
+				markdownSha256: hash,
+				answeredFieldCount: result.progressSummary.counts.answeredFields,
+				skippedFieldCount: result.progressSummary.counts.skippedFields
+			}
+		};
+		if (llmStats) turn.llm = llmStats;
+		this.turns.push(turn);
+	}
+	/**
 	* Check if the form is complete.
 	*/
 	isComplete() {
@@ -1162,8 +1321,7 @@ var FormHarness = class {
 	* Get the SHA256 hash of the current form markdown.
 	*/
 	getMarkdownHash() {
-		const markdown = serialize(this.form);
-		return createHash("sha256").update(markdown).digest("hex");
+		return sha256(serialize(this.form));
 	}
 	/**
 	* Filter issues based on maxFieldsPerTurn and maxGroupsPerTurn limits.
@@ -1266,7 +1424,9 @@ var MockAgent = class {
 	* Generate patches from the completed mock to address issues.
 	*
 	* Processes issues in priority order, generating patches for
-	* fields that have values in the completed mock.
+	* fields that have values in the completed mock. For fields with no
+	* value (empty optional fields), generates skip_field patches.
+	* Returns AgentResponse with patches but no stats (mock doesn't track LLM usage).
 	*/
 	async generatePatches(issues, _form, maxPatches) {
 		const patches = [];
@@ -1276,17 +1436,43 @@ var MockAgent = class {
 			if (issue.scope !== "field") continue;
 			const fieldId = issue.ref;
 			if (addressedFields.has(fieldId)) continue;
-			const completedValue = this.completedValues[fieldId];
-			if (!completedValue) continue;
 			const field = this.fieldMap.get(fieldId);
 			if (!field) continue;
+			const completedValue = this.completedValues[fieldId];
+			if (!completedValue || !this.hasValue(completedValue)) {
+				if (!field.required) {
+					patches.push({
+						op: "skip_field",
+						fieldId,
+						reason: "No value in mock form"
+					});
+					addressedFields.add(fieldId);
+				}
+				continue;
+			}
 			const patch = this.createPatch(fieldId, field, completedValue);
 			if (patch) {
 				patches.push(patch);
 				addressedFields.add(fieldId);
 			}
 		}
-		return Promise.resolve(patches);
+		return Promise.resolve({ patches });
+	}
+	/**
+	* Check if a field value actually has content (not null/empty).
+	*/
+	hasValue(value) {
+		switch (value.kind) {
+			case "string": return value.value !== null && value.value !== "";
+			case "number": return value.value !== null;
+			case "string_list": return value.items.length > 0;
+			case "single_select": return value.selected !== null;
+			case "multi_select": return value.selected.length > 0;
+			case "checkboxes": return true;
+			case "url": return value.value !== null && value.value !== "";
+			case "url_list": return value.items.length > 0;
+			default: return false;
+		}
 	}
 	/**
 	* Create a patch for a field based on its kind and completed value.
@@ -1323,6 +1509,16 @@ var MockAgent = class {
 				fieldId,
 				values: value.values
 			};
+			case "url": return {
+				op: "set_url",
+				fieldId,
+				value: value.value
+			};
+			case "url_list": return {
+				op: "set_url_list",
+				fieldId,
+				items: value.items
+			};
 			default: return null;
 		}
 	}
@@ -1337,6 +1533,104 @@ function createMockAgent(completedForm) {
 	return new MockAgent(completedForm);
 }
 
+//#endregion
+//#region src/harness/prompts.ts
+/**
+* Agent Prompts - Centralized prompt definitions for the live agent.
+*
+* All hardcoded prompts are defined here for easy review, modification,
+* and future configurability. This file serves as the single source of
+* truth for agent behavior instructions.
+*/
+/**
+* Default system prompt for the live agent.
+*
+* This is the base instruction set that defines the agent's core behavior
+* for form filling. It emphasizes accuracy over completeness and prohibits
+* fabrication of data.
+*/
+const DEFAULT_SYSTEM_PROMPT = `# Form Instructions
+Carefully research answers to all questions in the form, using all available tools you have.
+
+Guidelines:
+1. Focus on required fields first (severity: "required"), then address optional fields (severity: "recommended")
+2. You MUST address ALL issues shown to you - both required AND recommended (optional)
+3. NEVER fabricate or guess information - only use data you can verify
+4. If you cannot find verifiable information for a field, use skip_field to mark it as skipped with a reason
+5. For string fields: use appropriate text from verified sources
+6. For number fields: use appropriate numeric values from verified sources
+7. For single_select: choose one valid option ID
+8. For multi_select: choose one or more valid option IDs
+9. For checkboxes: set appropriate states (done/todo for simple, yes/no for explicit)
+
+CRITICAL: Accuracy is more important than completeness. Use skip_field when information cannot be verified.
+
+Always use the generatePatches tool to submit your field values.
+`;
+/**
+* Web search instructions appended when web search tools are available.
+*
+* These instructions enforce that the agent must verify all information
+* through web search before filling fields.
+*/
+const WEB_SEARCH_INSTRUCTIONS = `# Web Search
+You have access to web search tools. You MUST use them to verify ALL information before filling fields.
+
+Guidelines:
+1. Search for official sources (company websites, Crunchbase, LinkedIn, press releases)
+2. Cross-reference information across multiple sources when possible
+3. Only fill fields with data you found and verified through search
+4. If a search returns no results or uncertain information, use skip_field with a reason explaining what you searched for
+5. NEVER fill fields with guessed or assumed information
+`;
+/**
+* Description for the generatePatches tool.
+*
+* This tells the model how to use the patch submission tool.
+*/
+const GENERATE_PATCHES_TOOL_DESCRIPTION = "Generate patches to fill form fields. Each patch sets a field value. Use the field IDs from the issues list. Return patches for all issues you can address.";
+/**
+* Header for the issues section in the context prompt.
+*/
+const ISSUES_HEADER = "# Current Form Issues";
+/**
+* Template for the issues intro text.
+* @param maxPatches - Maximum number of patches to generate
+*/
+function getIssuesIntro(maxPatches) {
+	return `You need to address up to ${maxPatches} issues. Here are the current issues:`;
+}
+/**
+* Instructions section for the context prompt.
+*
+* This explains the patch format for each field type.
+*/
+const PATCH_FORMAT_INSTRUCTIONS = `# Instructions
+
+Use the generatePatches tool to submit patches for the fields above.
+Each patch should match the field type:
+- string: { op: "set_string", fieldId: "...", value: "..." }
+- number: { op: "set_number", fieldId: "...", value: 123 }
+- string_list: { op: "set_string_list", fieldId: "...", items: ["...", "..."] }
+- single_select: { op: "set_single_select", fieldId: "...", selected: "option_id" }
+- multi_select: { op: "set_multi_select", fieldId: "...", selected: ["opt1", "opt2"] }
+- checkboxes: { op: "set_checkboxes", fieldId: "...", values: { "opt1": "done", "opt2": "todo" } }
+- url: { op: "set_url", fieldId: "...", value: "https://..." }
+- url_list: { op: "set_url_list", fieldId: "...", items: ["https://...", "https://..."] }
+
+If you cannot find verifiable information for a field, skip it:
+- skip: { op: "skip_field", fieldId: "...", reason: "Information not available" }`;
+/**
+* Section headers used when building the composed system prompt.
+*/
+const SECTION_HEADERS = {
+	formInstructions: "# Form Instructions",
+	roleInstructions: (role) => `# Instructions for ${role} role`,
+	roleGuidance: "# Role guidance",
+	fieldInstructions: "# Field-specific instructions",
+	additionalContext: "# Additional Context"
+};
+
 //#endregion
 //#region src/harness/liveAgent.ts
 /**
@@ -1347,58 +1641,93 @@ var LiveAgent = class {
 	maxStepsPerTurn;
 	systemPromptAddition;
 	targetRole;
+	provider;
+	enableWebSearch;
+	webSearchTools = null;
 	constructor(config) {
 		this.model = config.model;
 		this.maxStepsPerTurn = config.maxStepsPerTurn ?? 3;
 		this.systemPromptAddition = config.systemPromptAddition;
 		this.targetRole = config.targetRole ?? AGENT_ROLE;
+		this.provider = config.provider;
+		this.enableWebSearch = config.enableWebSearch ?? true;
+		if (this.enableWebSearch && this.provider) this.webSearchTools = loadWebSearchTools(this.provider);
+	}
+	/**
+	* Get list of available tool names for this agent.
+	* Useful for logging what capabilities the agent has.
+	*/
+	getAvailableToolNames() {
+		const tools = ["generatePatches"];
+		if (this.webSearchTools) tools.push(...Object.keys(this.webSearchTools));
+		return tools;
 	}
 	/**
 	* Generate patches using the LLM.
 	*
-	* Calls the model with the current form state and issues,
-	* and extracts patches from the tool calls.
+	* Each call is stateless - the full form context is provided fresh each turn.
+	* The form itself carries all state (filled values, remaining issues).
+	* Returns patches and per-turn stats for observability.
 	*/
 	async generatePatches(issues, form, maxPatches) {
 		const contextPrompt = buildContextPrompt(issues, form, maxPatches);
 		let systemPrompt = buildSystemPrompt(form, this.targetRole, issues);
 		if (this.systemPromptAddition) systemPrompt += "\n\n# Additional Context\n" + this.systemPromptAddition;
-		const generatePatchesTool = {
-			description: "Generate patches to fill form fields. Each patch sets a field value. Use the field IDs from the issues list. Return patches for all issues you can address.",
-			inputSchema: zodSchema(z.object({ patches: z.array(PatchSchema).max(maxPatches).describe("Array of patches. Each patch sets a value for one field.") }))
+		if (this.enableWebSearch && this.provider && !this.webSearchTools) this.webSearchTools = loadWebSearchTools(this.provider);
+		if (this.webSearchTools && Object.keys(this.webSearchTools).length > 0) systemPrompt += "\n\n" + WEB_SEARCH_INSTRUCTIONS;
+		const tools = {
+			generatePatches: {
+				description: GENERATE_PATCHES_TOOL_DESCRIPTION,
+				inputSchema: zodSchema(z.object({ patches: z.array(PatchSchema).max(maxPatches).describe("Array of patches. Each patch sets a value for one field.") }))
+			},
+			...this.webSearchTools
 		};
 		const result = await generateText({
 			model: this.model,
 			system: systemPrompt,
 			prompt: contextPrompt,
-			tools: { generatePatches: generatePatchesTool },
+			tools,
 			stopWhen: stepCountIs(this.maxStepsPerTurn)
 		});
 		const patches = [];
-		for (const step of result.steps) for (const toolCall of step.toolCalls) if (toolCall.toolName === "generatePatches" && "input" in toolCall) {
-			const input = toolCall.input;
-			patches.push(...input.patches);
+		const toolCallCounts = /* @__PURE__ */ new Map();
+		for (const step of result.steps) for (const toolCall of step.toolCalls) {
+			const count = toolCallCounts.get(toolCall.toolName) ?? 0;
+			toolCallCounts.set(toolCall.toolName, count + 1);
+			if (toolCall.toolName === "generatePatches" && "input" in toolCall) {
+				const input = toolCall.input;
+				patches.push(...input.patches);
+			}
 		}
-		return patches.slice(0, maxPatches);
+		const toolCalls = [];
+		for (const [name, count] of toolCallCounts) toolCalls.push({
+			name,
+			count
+		});
+		const requiredRemaining = issues.filter((i) => i.severity === "required").length;
+		const optionalRemaining = issues.filter((i) => i.severity === "recommended").length;
+		const stats = {
+			inputTokens: result.usage?.inputTokens,
+			outputTokens: result.usage?.outputTokens,
+			toolCalls,
+			formProgress: {
+				answeredFields: Object.keys(form.valuesByFieldId).filter((id) => form.valuesByFieldId[id] !== null).length,
+				skippedFields: Object.keys(form.skipsByFieldId ?? {}).filter((id) => form.skipsByFieldId?.[id]?.skipped).length,
+				requiredRemaining,
+				optionalRemaining
+			},
+			prompts: {
+				system: systemPrompt,
+				context: contextPrompt
+			}
+		};
+		return {
+			patches: patches.slice(0, maxPatches),
+			stats
+		};
 	}
 };
 /**
-* Default system prompt for the live agent.
-*/
-const DEFAULT_SYSTEM_PROMPT = `You are a form-filling assistant. Your task is to analyze form issues and generate patches to fill in the required fields.
-
-Guidelines:
-1. Focus on required fields first (severity: "required")
-2. Use realistic but generic values when specific data is not provided
-3. Match the expected field types exactly
-4. For string fields: use appropriate text
-5. For number fields: use appropriate numeric values
-6. For single_select: choose one valid option ID
-7. For multi_select: choose one or more valid option IDs
-8. For checkboxes: set appropriate states (done/todo for simple, yes/no for explicit)
-
-Always use the generatePatches tool to submit your field values.`;
-/**
 * Extract doc blocks of a specific tag type for a given ref.
 */
 function getDocBlocks(docs, ref, tag) {
@@ -1419,19 +1748,19 @@ function buildSystemPrompt(form, targetRole, issues) {
 	const formInstructions = getDocBlocks(form.docs, form.schema.id, "instructions");
 	if (formInstructions.length > 0) {
 		sections.push("");
-		sections.push("# Form Instructions");
+		sections.push(SECTION_HEADERS.formInstructions);
 		for (const doc of formInstructions) sections.push(doc.bodyMarkdown.trim());
 	}
 	const roleInstructions = form.metadata?.roleInstructions?.[targetRole];
 	if (roleInstructions) {
 		sections.push("");
-		sections.push(`# Instructions for ${targetRole} role`);
+		sections.push(SECTION_HEADERS.roleInstructions(targetRole));
 		sections.push(roleInstructions);
 	} else {
 		const defaultRoleInstr = DEFAULT_ROLE_INSTRUCTIONS[targetRole];
 		if (defaultRoleInstr) {
 			sections.push("");
-			sections.push(`# Role guidance`);
+			sections.push(SECTION_HEADERS.roleGuidance);
 			sections.push(defaultRoleInstr);
 		}
 	}
@@ -1443,19 +1772,31 @@ function buildSystemPrompt(form, targetRole, issues) {
 	}
 	if (fieldInstructions.length > 0) {
 		sections.push("");
-		sections.push("# Field-specific instructions");
+		sections.push(SECTION_HEADERS.fieldInstructions);
 		sections.push(...fieldInstructions);
 	}
 	return sections.join("\n");
 }
 /**
-* Build a context prompt with issues and form information.
+* Build a context prompt with full form state and remaining issues.
+*
+* The form markdown shows the agent exactly what's been filled so far,
+* making each turn stateless - all state is in the form itself.
 */
 function buildContextPrompt(issues, form, maxPatches) {
 	const lines = [];
-	lines.push("# Current Form Issues");
+	lines.push("# Current Form State");
+	lines.push("");
+	lines.push("Below is the complete form with all currently filled values.");
+	lines.push("Fields marked with `[ ]` or empty values still need to be filled.");
 	lines.push("");
-	lines.push(`You need to address up to ${maxPatches} issues. Here are the current issues:`);
+	lines.push("```markdown");
+	lines.push(serialize(form));
+	lines.push("```");
+	lines.push("");
+	lines.push(ISSUES_HEADER);
+	lines.push("");
+	lines.push(getIssuesIntro(maxPatches));
 	lines.push("");
 	for (const issue of issues) {
 		lines.push(`- **${issue.ref}** (${issue.scope}): ${issue.message}`);
@@ -1473,16 +1814,7 @@ function buildContextPrompt(issues, form, maxPatches) {
 		}
 		lines.push("");
 	}
-	lines.push("# Instructions");
-	lines.push("");
-	lines.push("Use the generatePatches tool to submit patches for the fields above.");
-	lines.push("Each patch should match the field type:");
-	lines.push("- string: { op: \"set_string\", fieldId: \"...\", value: \"...\" }");
-	lines.push("- number: { op: \"set_number\", fieldId: \"...\", value: 123 }");
-	lines.push("- string_list: { op: \"set_string_list\", fieldId: \"...\", items: [\"...\", \"...\"] }");
-	lines.push("- single_select: { op: \"set_single_select\", fieldId: \"...\", selected: \"option_id\" }");
-	lines.push("- multi_select: { op: \"set_multi_select\", fieldId: \"...\", selected: [\"opt1\", \"opt2\"] }");
-	lines.push("- checkboxes: { op: \"set_checkboxes\", fieldId: \"...\", values: { \"opt1\": \"done\", \"opt2\": \"todo\" } }");
+	lines.push(PATCH_FORMAT_INSTRUCTIONS);
 	return lines.join("\n");
 }
 /**
@@ -1493,6 +1825,26 @@ function findField(form, fieldId) {
 	return null;
 }
 /**
+* Load web search tools for a provider.
+*
+* Uses statically imported provider modules to get web search tools.
+* Returns empty object if provider doesn't support web search.
+*/
+function loadWebSearchTools(provider) {
+	if (!getWebSearchConfig(provider)) return {};
+	switch (provider) {
+		case "openai":
+			if (openai.tools?.webSearch) return { web_search: openai.tools.webSearch({}) };
+			if (openai.tools?.webSearchPreview) return { web_search: openai.tools.webSearchPreview({}) };
+			return {};
+		case "google":
+			if (google.tools?.googleSearch) return { google_search: google.tools.googleSearch({}) };
+			return {};
+		case "xai": return {};
+		default: return {};
+	}
+}
+/**
 * Create a live agent with the given configuration.
 */
 function createLiveAgent(config) {
@@ -1692,6 +2044,7 @@ async function fillForm(options) {
 					groups: []
 				},
 				valuesByFieldId: {},
+				skipsByFieldId: {},
 				docs: [],
 				orderIndex: [],
 				idIndex: /* @__PURE__ */ new Map()
@@ -1701,9 +2054,13 @@ async function fillForm(options) {
 		};
 	}
 	let model;
+	let provider;
 	if (!options._testAgent) try {
-		if (typeof options.model === "string") model = (await resolveModel(options.model)).model;
-		else model = options.model;
+		if (typeof options.model === "string") {
+			const resolved = await resolveModel(options.model);
+			model = resolved.model;
+			provider = resolved.provider;
+		} else model = options.model;
 	} catch (error) {
 		const message = error instanceof Error ? error.message : String(error);
 		return buildErrorResult(form, [`Model resolution error: ${message}`], []);
@@ -1733,7 +2090,9 @@ async function fillForm(options) {
 	const agent = options._testAgent ?? createLiveAgent({
 		model,
 		systemPromptAddition: options.systemPromptAddition,
-		targetRole: targetRoles[0] ?? AGENT_ROLE
+		targetRole: targetRoles[0] ?? AGENT_ROLE,
+		provider,
+		enableWebSearch: true
 	});
 	let turnCount = 0;
 	let stepResult = harness.step();
@@ -1742,12 +2101,18 @@ async function fillForm(options) {
 			ok: false,
 			reason: "cancelled"
 		}, inputContextWarnings, stepResult.issues);
-		const patches = await agent.generatePatches(stepResult.issues, form, maxPatchesPerTurn);
+		const { patches, stats } = await agent.generatePatches(stepResult.issues, form, maxPatchesPerTurn);
 		if (options.signal?.aborted) return buildResult(form, turnCount, totalPatches, {
 			ok: false,
 			reason: "cancelled"
 		}, inputContextWarnings, stepResult.issues);
-		stepResult = harness.apply(patches, stepResult.issues);
+		let llmStats;
+		if (stats) llmStats = {
+			inputTokens: stats.inputTokens,
+			outputTokens: stats.outputTokens,
+			toolCalls: stats.toolCalls.length > 0 ? stats.toolCalls : void 0
+		};
+		stepResult = harness.apply(patches, stepResult.issues, llmStats);
 		totalPatches += patches.length;
 		turnCount++;
 		if (options.onTurnComplete) try {
@@ -1757,10 +2122,11 @@ async function fillForm(options) {
 				issuesShown: stepResult.issues.length,
 				patchesApplied: patches.length,
 				requiredIssuesRemaining: requiredIssues.length,
-				isComplete: stepResult.isComplete
+				isComplete: stepResult.isComplete,
+				stats
 			});
 		} catch {}
-		if (!stepResult.isComplete) stepResult = harness.step();
+		if (!stepResult.isComplete && !harness.hasReachedMaxTurns()) stepResult = harness.step();
 	}
 	if (stepResult.isComplete) return buildResult(form, turnCount, totalPatches, { ok: true }, inputContextWarnings);
 	return buildResult(form, turnCount, totalPatches, {