markform 0.1.11 → 0.1.13

package/dist/index.mjs

@@ -1,7 +1,7 @@
 
-import { $ as SetUrlListPatchSchema, A as MultiCheckboxStateSchema, At as WireToolResultSchema, B as ProgressSummarySchema, C as HarnessConfigSchema, Ct as ValidationIssueSchema, D as IssueReasonSchema, Dt as WireResponseFormatSchema, E as InspectResultSchema, Et as WireRequestFormatSchema, F as OptionIdSchema, G as SetCheckboxesPatchSchema, H as SessionFinalSchema, I as OptionSchema, J as SetNumberPatchSchema, K as SetDatePatchSchema, L as PatchSchema, M as MultiSelectValueSchema, Mt as YearValueSchema, N as NumberFieldSchema, O as IssueScopeSchema, Ot as WireResponseStepSchema, P as NumberValueSchema, Q as SetTablePatchSchema, R as ProgressCountsSchema, S as FormSchemaSchema, St as UrlValueSchema, T as InspectIssueSchema, Tt as WireFormatSchema, U as SessionTranscriptSchema, V as RunModeSchema, W as SessionTurnSchema, X as SetStringListPatchSchema, Y as SetSingleSelectPatchSchema, Z as SetStringPatchSchema, _ as FieldKindSchema, _t as TableRowResponseSchema, a as CheckboxProgressCountsSchema, at as SingleSelectValueSchema, b as FieldSchema, bt as UrlListFieldSchema, c as CheckboxesValueSchema, ct as StepResultSchema, d as DateFieldSchema, dt as StringListValueSchema, et as SetUrlPatchSchema, f as DateValueSchema, ft as StringValueSchema, g as FieldGroupSchema, gt as TableRowPatchSchema, h as ExplicitCheckboxValueSchema, ht as TableFieldSchema, i as CheckboxModeSchema, it as SingleSelectFieldSchema, j as MultiSelectFieldSchema, jt as YearFieldSchema, k as MarkformFrontmatterSchema, kt as WireToolCallSchema, l as ClearFieldPatchSchema, lt as StringFieldSchema, m as DocumentationTagSchema, mt as TableColumnSchema, n as ApplyResultSchema, nt as SeveritySchema, o as CheckboxValueSchema, ot as SourcePositionSchema, p as DocumentationBlockSchema, pt as StructureSummarySchema, q as SetMultiSelectPatchSchema, r as CellResponseSchema, rt as SimpleCheckboxStateSchema, s as CheckboxesFieldSchema, st as SourceRangeSchema, t as AnswerStateSchema, tt as SetYearPatchSchema, u as ColumnTypeNameSchema, ut as StringListFieldSchema, v as FieldProgressSchema, vt as TableValueSchema, w as IdSchema, wt as ValidatorRefSchema, x as FieldValueSchema, xt as UrlListValueSchema, y as FieldResponseSchema, yt as UrlFieldSchema, z as ProgressStateSchema } from "./coreTypes-Z8SvQyoL.mjs";
-import { $ as isPatchError, B as MarkformAbortError, G as MarkformPatchError, H as MarkformError, J as isAbortError, K as MarkformValidationError, Q as isParseError, U as MarkformLlmError, V as MarkformConfigError, W as MarkformParseError, X as isLlmError, Y as isConfigError, Z as isMarkformError, a as validate, c as computeProgressSummary, d as serializeForm, et as isRetryableError, i as inspect, l as computeStructureSummary, o as computeAllSummaries, p as serializeReport, q as ParseError, s as computeFormState, t as applyPatches, tt as isValidationError, u as isFormComplete } from "./apply-yfRtNIHc.mjs";
-import { A as parseRawTable, C as parseScopeRef, D as parseForm, E as formToJsonSchema, O as parseCellValue, S as isQualifiedRef, T as fieldToJsonSchema, _ as coerceToFieldPatch, a as resolveHarnessConfig, b as isCellRef, f as MockAgent, g as coerceInputContext, h as createHarness, i as runResearch, k as parseMarkdownTable, m as FormHarness, n as isResearchForm, o as fillForm, p as createMockAgent, r as validateResearchForm, t as VERSION, v as findFieldById, w as serializeScopeRef, x as isFieldRef, y as getFieldId } from "./src-ozWOSQTW.mjs";
-import { n as serializeSession, t as parseSession } from "./session-DX-DvjRP.mjs";
+import { $ as SetUrlListPatchSchema, A as MultiCheckboxStateSchema, At as WireToolResultSchema, B as ProgressSummarySchema, C as HarnessConfigSchema, Ct as ValidationIssueSchema, D as IssueReasonSchema, Dt as WireResponseFormatSchema, E as InspectResultSchema, Et as WireRequestFormatSchema, F as OptionIdSchema, G as SetCheckboxesPatchSchema, H as SessionFinalSchema, I as OptionSchema, J as SetNumberPatchSchema, K as SetDatePatchSchema, L as PatchSchema, M as MultiSelectValueSchema, Mt as YearValueSchema, N as NumberFieldSchema, O as IssueScopeSchema, Ot as WireResponseStepSchema, P as NumberValueSchema, Q as SetTablePatchSchema, R as ProgressCountsSchema, S as FormSchemaSchema, St as UrlValueSchema, T as InspectIssueSchema, Tt as WireFormatSchema, U as SessionTranscriptSchema, V as RunModeSchema, W as SessionTurnSchema, X as SetStringListPatchSchema, Y as SetSingleSelectPatchSchema, Z as SetStringPatchSchema, _ as FieldKindSchema, _t as TableRowResponseSchema, a as CheckboxProgressCountsSchema, at as SingleSelectValueSchema, b as FieldSchema, bt as UrlListFieldSchema, c as CheckboxesValueSchema, ct as StepResultSchema, d as DateFieldSchema, dt as StringListValueSchema, et as SetUrlPatchSchema, f as DateValueSchema, ft as StringValueSchema, g as FieldGroupSchema, gt as TableRowPatchSchema, h as ExplicitCheckboxValueSchema, ht as TableFieldSchema, i as CheckboxModeSchema, it as SingleSelectFieldSchema, j as MultiSelectFieldSchema, jt as YearFieldSchema, k as MarkformFrontmatterSchema, kt as WireToolCallSchema, l as ClearFieldPatchSchema, lt as StringFieldSchema, m as DocumentationTagSchema, mt as TableColumnSchema, n as ApplyResultSchema, nt as SeveritySchema, o as CheckboxValueSchema, ot as SourcePositionSchema, p as DocumentationBlockSchema, pt as StructureSummarySchema, q as SetMultiSelectPatchSchema, r as CellResponseSchema, rt as SimpleCheckboxStateSchema, s as CheckboxesFieldSchema, st as SourceRangeSchema, t as AnswerStateSchema, tt as SetYearPatchSchema, u as ColumnTypeNameSchema, ut as StringListFieldSchema, v as FieldProgressSchema, vt as TableValueSchema, w as IdSchema, wt as ValidatorRefSchema, x as FieldValueSchema, xt as UrlListValueSchema, y as FieldResponseSchema, yt as UrlFieldSchema, z as ProgressStateSchema } from "./coreTypes-Big8sgih.mjs";
+import { $ as isParseError, G as MarkformParseError, H as MarkformConfigError, J as ParseError, K as MarkformPatchError, Q as isMarkformError, U as MarkformError, V as MarkformAbortError, W as MarkformLlmError, X as isConfigError, Y as isAbortError, Z as isLlmError, a as validate, c as computeProgressSummary, d as serializeForm, et as isPatchError, i as inspect, l as computeStructureSummary, nt as isValidationError, o as computeAllSummaries, p as serializeReport, q as MarkformValidationError, s as computeFormState, t as applyPatches, tt as isRetryableError, u as isFormComplete } from "./apply-D5FLd9Yp.mjs";
+import { A as parseRawTable, C as parseScopeRef, D as parseForm, E as formToJsonSchema, O as parseCellValue, S as isQualifiedRef, T as fieldToJsonSchema, _ as coerceToFieldPatch, a as resolveHarnessConfig, b as isCellRef, f as MockAgent, g as coerceInputContext, h as createHarness, i as runResearch, k as parseMarkdownTable, m as FormHarness, n as isResearchForm, o as fillForm, p as createMockAgent, r as validateResearchForm, t as VERSION, v as findFieldById, w as serializeScopeRef, x as isFieldRef, y as getFieldId } from "./src-DuA3kv-E.mjs";
+import { n as serializeSession, t as parseSession } from "./session-CrhOG4eH.mjs";
 
 export { AnswerStateSchema, ApplyResultSchema, CellResponseSchema, CheckboxModeSchema, CheckboxProgressCountsSchema, CheckboxValueSchema, CheckboxesFieldSchema, CheckboxesValueSchema, ClearFieldPatchSchema, ColumnTypeNameSchema, DateFieldSchema, DateValueSchema, DocumentationBlockSchema, DocumentationTagSchema, ExplicitCheckboxValueSchema, FieldGroupSchema, FieldKindSchema, FieldProgressSchema, FieldResponseSchema, FieldSchema, FieldValueSchema, FormHarness, FormSchemaSchema, HarnessConfigSchema, IdSchema, InspectIssueSchema, InspectResultSchema, IssueReasonSchema, IssueScopeSchema, MarkformAbortError, MarkformConfigError, MarkformError, MarkformFrontmatterSchema, MarkformLlmError, MarkformParseError, MarkformPatchError, MarkformValidationError, MockAgent, MultiCheckboxStateSchema, MultiSelectFieldSchema, MultiSelectValueSchema, NumberFieldSchema, NumberValueSchema, OptionIdSchema, OptionSchema, ParseError, PatchSchema, ProgressCountsSchema, ProgressStateSchema, ProgressSummarySchema, RunModeSchema, SessionFinalSchema, SessionTranscriptSchema, SessionTurnSchema, SetCheckboxesPatchSchema, SetDatePatchSchema, SetMultiSelectPatchSchema, SetNumberPatchSchema, SetSingleSelectPatchSchema, SetStringListPatchSchema, SetStringPatchSchema, SetTablePatchSchema, SetUrlListPatchSchema, SetUrlPatchSchema, SetYearPatchSchema, SeveritySchema, SimpleCheckboxStateSchema, SingleSelectFieldSchema, SingleSelectValueSchema, SourcePositionSchema, SourceRangeSchema, StepResultSchema, StringFieldSchema, StringListFieldSchema, StringListValueSchema, StringValueSchema, StructureSummarySchema, TableColumnSchema, TableFieldSchema, TableRowPatchSchema, TableRowResponseSchema, TableValueSchema, UrlFieldSchema, UrlListFieldSchema, UrlListValueSchema, UrlValueSchema, VERSION, ValidationIssueSchema, ValidatorRefSchema, WireFormatSchema, WireRequestFormatSchema, WireResponseFormatSchema, WireResponseStepSchema, WireToolCallSchema, WireToolResultSchema, YearFieldSchema, YearValueSchema, applyPatches, coerceInputContext, coerceToFieldPatch, computeAllSummaries, computeFormState, computeProgressSummary, computeStructureSummary, createHarness, createMockAgent, fieldToJsonSchema, fillForm, findFieldById, formToJsonSchema, getFieldId, inspect, isAbortError, isCellRef, isConfigError, isFieldRef, isFormComplete, isLlmError, isMarkformError, isParseError, isPatchError, isQualifiedRef, isResearchForm, isRetryableError, isValidationError, parseCellValue, parseForm, parseMarkdownTable, parseRawTable, parseScopeRef, parseSession, resolveHarnessConfig, runResearch, serializeForm, serializeReport, serializeScopeRef, serializeSession, validate, validateResearchForm };

package/dist/{session-BJe-hei3.mjs → session-7QJlUeNg.mjs}

@@ -1,4 +1,4 @@
 
-import { n as serializeSession, t as parseSession } from "./session-DX-DvjRP.mjs";
+import { n as serializeSession, t as parseSession } from "./session-CrhOG4eH.mjs";
 
 export { serializeSession };

package/dist/{session-DX-DvjRP.mjs → session-CrhOG4eH.mjs}

@@ -1,5 +1,5 @@
 
-import { U as SessionTranscriptSchema } from "./coreTypes-Z8SvQyoL.mjs";
+import { U as SessionTranscriptSchema } from "./coreTypes-Big8sgih.mjs";
 import YAML from "yaml";
 
 //#region src/engine/session.ts

package/dist/{src-ozWOSQTW.mjs → src-DuA3kv-E.mjs}

@@ -1,6 +1,6 @@
 
-import { L as PatchSchema, V as RunModeSchema } from "./coreTypes-Z8SvQyoL.mjs";
-import { C as DEFAULT_RESEARCH_MAX_PATCHES_PER_TURN, L as getWebSearchConfig, S as DEFAULT_RESEARCH_MAX_ISSUES_PER_TURN, T as DEFAULT_ROLE_INSTRUCTIONS, V as MarkformConfigError, W as MarkformParseError, _ as DEFAULT_MAX_ISSUES_PER_TURN, d as serializeForm, i as inspect, m as AGENT_ROLE, r as getFieldsForRoles, t as applyPatches, v as DEFAULT_MAX_PATCHES_PER_TURN, w as DEFAULT_ROLES, x as DEFAULT_PRIORITY, y as DEFAULT_MAX_TURNS } from "./apply-yfRtNIHc.mjs";
+import { L as PatchSchema, V as RunModeSchema } from "./coreTypes-Big8sgih.mjs";
+import { C as DEFAULT_RESEARCH_MAX_ISSUES_PER_TURN, E as DEFAULT_ROLE_INSTRUCTIONS, G as MarkformParseError, H as MarkformConfigError, R as getWebSearchConfig, S as DEFAULT_PRIORITY, T as DEFAULT_ROLES, _ as DEFAULT_MAX_ISSUES_PER_TURN, b as DEFAULT_MAX_TURNS, d as serializeForm, i as inspect, m as AGENT_ROLE, r as getFieldsForRoles, t as applyPatches, v as DEFAULT_MAX_PATCHES_PER_TURN, w as DEFAULT_RESEARCH_MAX_PATCHES_PER_TURN, y as DEFAULT_MAX_STEPS_PER_TURN } from "./apply-D5FLd9Yp.mjs";
 import { z } from "zod";
 import Markdoc from "@markdoc/markdoc";
 import YAML from "yaml";
@@ -2538,12 +2538,12 @@ var FormHarness = class {
 		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 applyResult = applyPatches(this.form, patches);
-		const patchesActuallyApplied = applyResult.applyStatus === "applied" ? patches.length : 0;
+		const patchesActuallyApplied = applyResult.appliedPatches.length;
 		const result = inspect(this.form, { targetRoles: this.config.targetRoles });
 		const stepResult = this.computeStepResult(result);
 		stepResult.patchesApplied = patchesActuallyApplied;
 		stepResult.rejectedPatches = applyResult.rejectedPatches;
-		this.recordTurn(issues, patches, result, llmStats, context, applyResult.rejectedPatches, wire);
+		this.recordTurn(issues, patches, result, llmStats, context, applyResult.rejectedPatches, applyResult.warnings, wire);
 		if (stepResult.issues.length === 0 || this.turnNumber >= this.config.maxTurns) this.state = "complete";
 		else this.state = "wait";
 		return stepResult;
@@ -2567,7 +2567,7 @@ var FormHarness = class {
 	/**
 	* Record a turn in the session transcript.
 	*/
-	recordTurn(issues, patches, result, llmStats, context, rejectedPatches, wire) {
+	recordTurn(issues, patches, result, llmStats, context, rejectedPatches, warnings, wire) {
 		const hash = sha256(serializeForm(this.form));
 		const requiredIssueCount = result.issues.filter((i) => i.severity === "required").length;
 		const turn = {
@@ -2575,7 +2575,8 @@ var FormHarness = class {
 			inspect: { issues },
 			apply: {
 				patches,
-				...rejectedPatches && rejectedPatches.length > 0 && { rejectedPatches }
+				...rejectedPatches && rejectedPatches.length > 0 && { rejectedPatches },
+				...warnings && warnings.length > 0 && { warnings }
 			},
 			after: {
 				requiredIssueCount,
@@ -7916,15 +7917,15 @@ function getIssuesIntro(issueCount) {
 const PATCH_FORMATS = {
 	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\" } }",
+	string_list: "{ op: \"set_string_list\", fieldId: \"...\", value: [\"...\", \"...\"] }",
+	single_select: "{ op: \"set_single_select\", fieldId: \"...\", value: \"option_id\" }",
+	multi_select: "{ op: \"set_multi_select\", fieldId: \"...\", value: [\"opt1\", \"opt2\"] }",
+	checkboxes: "{ op: \"set_checkboxes\", fieldId: \"...\", value: { \"opt1\": \"done\", \"opt2\": \"todo\" } }",
 	url: "{ op: \"set_url\", fieldId: \"...\", value: \"https://...\" }",
-	url_list: "{ op: \"set_url_list\", fieldId: \"...\", items: [\"https://...\", \"https://...\"] }",
+	url_list: "{ op: \"set_url_list\", fieldId: \"...\", value: [\"https://...\", \"https://...\"] }",
 	date: "{ op: \"set_date\", fieldId: \"...\", value: \"2024-01-15\" }",
 	year: "{ op: \"set_year\", fieldId: \"...\", value: 2024 }",
-	table: "{ op: \"set_table\", fieldId: \"...\", rows: [{ col1: \"value1\", col2: \"value2\" }, ...] }"
+	table: "{ op: \"set_table\", fieldId: \"...\", value: [{ col1: \"value1\", col2: \"value2\" }, ...] }"
 };
 /**
 * Get the correct patch format for a field kind.
@@ -8011,7 +8012,7 @@ var LiveAgent = class {
 	callbacks;
 	constructor(config) {
 		this.model = config.model;
-		this.maxStepsPerTurn = config.maxStepsPerTurn ?? 3;
+		this.maxStepsPerTurn = config.maxStepsPerTurn ?? DEFAULT_MAX_STEPS_PER_TURN;
 		this.systemPromptAddition = config.systemPromptAddition;
 		this.targetRole = config.targetRole ?? AGENT_ROLE;
 		this.provider = config.provider;
@@ -8708,12 +8709,14 @@ async function fillForm(options) {
 		}
 		inputContextWarnings = coercionResult.warnings;
 	}
-	const maxTurns = options.maxTurns ?? DEFAULT_MAX_TURNS;
+	const maxTurnsTotal = options.maxTurnsTotal ?? DEFAULT_MAX_TURNS;
+	const startingTurnNumber = options.startingTurnNumber ?? 0;
 	const maxPatchesPerTurn = options.maxPatchesPerTurn ?? DEFAULT_MAX_PATCHES_PER_TURN;
 	const maxIssuesPerTurn = options.maxIssuesPerTurn ?? DEFAULT_MAX_ISSUES_PER_TURN;
 	const targetRoles = options.targetRoles ?? [AGENT_ROLE];
+	const remainingTurns = Math.max(0, maxTurnsTotal - startingTurnNumber);
 	const harness = createHarness(form, {
-		maxTurns,
+		maxTurns: remainingTurns,
 		maxPatchesPerTurn,
 		maxIssuesPerTurn,
 		targetRoles,
@@ -8726,12 +8729,19 @@ async function fillForm(options) {
 		provider,
 		enableWebSearch: options.enableWebSearch,
 		additionalTools: options.additionalTools,
-		callbacks: options.callbacks
+		callbacks: options.callbacks,
+		maxStepsPerTurn: options.maxStepsPerTurn
 	});
-	let turnCount = 0;
+	let turnCount = startingTurnNumber;
+	let turnsThisCall = 0;
 	let stepResult = harness.step();
 	let previousRejections;
 	while (!stepResult.isComplete && !harness.hasReachedMaxTurns()) {
+		if (options.maxTurnsThisCall !== void 0 && turnsThisCall >= options.maxTurnsThisCall) return buildResult(form, turnCount, totalPatches, {
+			ok: false,
+			reason: "batch_limit",
+			message: `Reached per-call limit (${options.maxTurnsThisCall} turns)`
+		}, inputContextWarnings, stepResult.issues);
 		if (options.signal?.aborted) return buildResult(form, turnCount, totalPatches, {
 			ok: false,
 			reason: "cancelled"
@@ -8779,6 +8789,7 @@ async function fillForm(options) {
 		const actualPatchesApplied = stepResult.patchesApplied ?? patches.length;
 		totalPatches += actualPatchesApplied;
 		turnCount++;
+		turnsThisCall++;
 		previousRejections = stepResult.rejectedPatches;
 		if (options.callbacks?.onTurnComplete) try {
 			const requiredIssues = stepResult.issues.filter((i) => i.severity === "required");
@@ -8800,7 +8811,7 @@ async function fillForm(options) {
 	return buildResult(form, turnCount, totalPatches, {
 		ok: false,
 		reason: "max_turns",
-		message: `Reached maximum turns (${maxTurns})`
+		message: `Reached maximum total turns (${maxTurnsTotal})`
 	}, inputContextWarnings, stepResult.issues);
 }
 
@@ -8821,7 +8832,7 @@ async function fillForm(options) {
 function resolveHarnessConfig(form, options) {
 	const frontmatterConfig = form.metadata?.harnessConfig;
 	return {
-		maxTurns: options?.maxTurns ?? frontmatterConfig?.maxTurns ?? DEFAULT_MAX_TURNS,
+		maxTurns: options?.maxTurnsTotal ?? frontmatterConfig?.maxTurns ?? DEFAULT_MAX_TURNS,
 		maxPatchesPerTurn: options?.maxPatchesPerTurn ?? frontmatterConfig?.maxPatchesPerTurn ?? DEFAULT_MAX_PATCHES_PER_TURN,
 		maxIssuesPerTurn: options?.maxIssuesPerTurn ?? frontmatterConfig?.maxIssuesPerTurn ?? DEFAULT_MAX_ISSUES_PER_TURN,
 		targetRoles: options?.targetRoles,
@@ -8849,7 +8860,7 @@ async function runResearch(form, options) {
 	const { model, provider } = await resolveModel(modelSpec);
 	const config = {
 		...resolveHarnessConfig(form, options),
-		maxTurns: options.maxTurns ?? form.metadata?.harnessConfig?.maxTurns ?? DEFAULT_MAX_TURNS,
+		maxTurns: options.maxTurnsTotal ?? form.metadata?.harnessConfig?.maxTurns ?? DEFAULT_MAX_TURNS,
 		maxIssuesPerTurn: options.maxIssuesPerTurn ?? form.metadata?.harnessConfig?.maxIssuesPerTurn ?? DEFAULT_RESEARCH_MAX_ISSUES_PER_TURN,
 		maxPatchesPerTurn: options.maxPatchesPerTurn ?? form.metadata?.harnessConfig?.maxPatchesPerTurn ?? DEFAULT_RESEARCH_MAX_PATCHES_PER_TURN,
 		targetRoles: options.targetRoles ?? [AGENT_ROLE],
@@ -8948,7 +8959,7 @@ function validateResearchForm(form) {
 //#endregion
 //#region src/index.ts
 /** Markform version (injected at build time). */
-const VERSION = "0.1.11";
+const VERSION = "0.1.13";
 
 //#endregion
 export { parseRawTable as A, parseScopeRef as C, parseForm as D, formToJsonSchema as E, parseCellValue as O, isQualifiedRef as S, fieldToJsonSchema as T, coerceToFieldPatch as _, resolveHarnessConfig as a, isCellRef as b, getProviderNames as c, createLiveAgent as d, MockAgent as f, coerceInputContext as g, createHarness as h, runResearch as i, parseMarkdownTable as k, resolveModel as l, FormHarness as m, isResearchForm as n, fillForm as o, createMockAgent as p, validateResearchForm as r, getProviderInfo as s, VERSION as t, buildMockWireFormat as u, findFieldById as v, serializeScopeRef as w, isFieldRef as x, getFieldId as y };

package/docs/markform-apis.md

@@ -53,11 +53,13 @@ Generate a filtered markdown report suitable for sharing.
 Produces clean, readable markdown with:
 
 - Fields and groups with `report=false` excluded
+
 - Documentation blocks with `report=false` excluded
+
 - Instructions blocks excluded by default (unless `report=true`)
 
-This is useful for generating shareable reports from completed forms without
-internal instructions or agent-only content.
+This is useful for generating shareable reports from completed forms without internal
+instructions or agent-only content.
 
 ### validate(form: ParsedForm, options?: ValidateOptions): ValidateResult
 
@@ -127,14 +129,15 @@ Each patch has an `op` and `fieldId`.
 | --- | --- | --- |
 | `set_string` | string | `{ "op": "set_string", "fieldId": "name", "value": "Alice" }` |
 | `set_number` | number | `{ "op": "set_number", "fieldId": "age", "value": 25 }` |
-| `set_string_list` | string_list | `{ "op": "set_string_list", "fieldId": "tags", "items": ["a", "b"] }` |
-| `set_single_select` | single_select | `{ "op": "set_single_select", "fieldId": "rating", "selected": "high" }` |
-| `set_multi_select` | multi_select | `{ "op": "set_multi_select", "fieldId": "cats", "selected": ["a", "b"] }` |
-| `set_checkboxes` | checkboxes | `{ "op": "set_checkboxes", "fieldId": "tasks", "values": {"item1": "done"} }` |
+| `set_string_list` | string_list | `{ "op": "set_string_list", "fieldId": "tags", "value": ["a", "b"] }` |
+| `set_single_select` | single_select | `{ "op": "set_single_select", "fieldId": "rating", "value": "high" }` |
+| `set_multi_select` | multi_select | `{ "op": "set_multi_select", "fieldId": "cats", "value": ["a", "b"] }` |
+| `set_checkboxes` | checkboxes | `{ "op": "set_checkboxes", "fieldId": "tasks", "value": {"item1": "done"} }` |
 | `set_url` | url | `{ "op": "set_url", "fieldId": "website", "value": "https://..." }` |
-| `set_url_list` | url_list | `{ "op": "set_url_list", "fieldId": "sources", "items": ["https://..."] }` |
+| `set_url_list` | url_list | `{ "op": "set_url_list", "fieldId": "sources", "value": ["https://..."] }` |
 | `set_date` | date | `{ "op": "set_date", "fieldId": "deadline", "value": "2024-06-15" }` |
 | `set_year` | year | `{ "op": "set_year", "fieldId": "founded", "value": 2015 }` |
+| `set_table` | table | `{ "op": "set_table", "fieldId": "data", "value": [{"col1": "v1"}] }` |
 | `clear_field` | any | `{ "op": "clear_field", "fieldId": "name" }` |
 | `skip_field` | optional | `{ "op": "skip_field", "fieldId": "notes", "reason": "Not applicable" }` |
 | `abort_field` | any | `{ "op": "abort_field", "fieldId": "data", "reason": "Unable to find" }` |
@@ -176,14 +179,91 @@ const result = await fillForm({
   form: parsedForm,
   model: 'anthropic/claude-sonnet-4-5',
   enableWebSearch: true,
+  captureWireFormat: false,
   targetRoles: ['agent'],
 });
 ```
 
+**FillOptions fields:**
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `form` | `string \| ParsedForm` | (required) | Form markdown or parsed form |
+| `model` | `string \| LanguageModel` | (required) | Model identifier or instance |
+| `enableWebSearch` | `boolean` | (required) | Enable provider web search tools |
+| `captureWireFormat` | `boolean` | (required) | Capture full LLM request/response |
+| `inputContext` | `InputContext` | `undefined` | Pre-fill fields by ID |
+| `systemPromptAddition` | `string` | `undefined` | Additional system prompt context |
+| `maxTurnsTotal` | `number` | `100` | Maximum TOTAL turns across all calls (safety limit) |
+| `maxTurnsThisCall` | `number` | `undefined` | Per-call turn limit for resumable fills |
+| `startingTurnNumber` | `number` | `0` | Starting turn for progress tracking |
+| `maxPatchesPerTurn` | `number` | `20` | Maximum patches per turn |
+| `maxIssuesPerTurn` | `number` | `10` | Maximum issues shown per turn |
+| `maxStepsPerTurn` | `number` | `20` | Maximum AI SDK steps (tool call rounds) per turn |
+| `targetRoles` | `string[]` | `['agent']` | Roles to fill |
+| `fillMode` | `FillMode` | `'continue'` | `'continue'` or `'overwrite'` |
+| `callbacks` | `FillCallbacks` | `undefined` | Progress callbacks |
+| `signal` | `AbortSignal` | `undefined` | Cancellation signal |
+| `additionalTools` | `Record<string, Tool>` | `undefined` | Custom tools for agent |
+
+### FillStatus
+
+The `status` field in `FillResult` indicates success or failure:
+
+| Status | Description |
+| --- | --- |
+| `{ ok: true }` | Form completed successfully |
+| `{ ok: false, reason: 'max_turns' }` | Hit overall `maxTurnsTotal` safety limit |
+| `{ ok: false, reason: 'batch_limit' }` | Hit `maxTurnsThisCall` per-call limit |
+| `{ ok: false, reason: 'cancelled' }` | Aborted via signal |
+| `{ ok: false, reason: 'error' }` | Unexpected error |
+
+### Resumable Form Fills
+
+For orchestrated environments with timeout constraints (e.g., Convex, AWS Step
+Functions), use `maxTurnsThisCall` to limit turns per call and resume from checkpoints.
+
+```typescript
+import { fillForm } from 'markform';
+
+// First call - limit to 2 turns
+const r1 = await fillForm({
+  form: formMarkdown,
+  model: 'anthropic/claude-sonnet-4-5',
+  enableWebSearch: false,
+  captureWireFormat: false,
+  maxTurnsThisCall: 2, // Stop after 2 turns
+});
+
+if (!r1.status.ok && r1.status.reason === 'batch_limit') {
+  // Resume from checkpoint using r1.markdown
+  const r2 = await fillForm({
+    form: r1.markdown,           // Use checkpoint as input
+    model: 'anthropic/claude-sonnet-4-5',
+    enableWebSearch: false,
+    captureWireFormat: false,
+    startingTurnNumber: r1.turns, // Continue turn count
+  });
+
+  console.log('Total turns:', r2.turns);
+  console.log('Status:', r2.status);
+}
+```
+
+**Key points:**
+
+- `maxTurnsThisCall` limits turns in a single call, returns `batch_limit` when reached
+
+- `result.markdown` contains the form checkpoint (serialized state)
+
+- `startingTurnNumber` ensures accurate progress tracking across calls
+
+- The form itself is the state—no session storage needed
+
 ### FillCallbacks
 
 Optional callbacks for observing form-filling execution in real-time.
-All callbacks are optional and errors in callbacks don't abort filling.
+All callbacks are optional and errors in callbacks don’t abort filling.
 
 ```typescript
 import type { FillCallbacks } from 'markform';

package/docs/markform-spec.md

@@ -127,10 +127,11 @@ markform:
 
 **Optional metadata fields:**
 
-- `run_mode` (*recommended*): Suggests how CLI tools should execute this form. Values:
-  `interactive` (user fills via prompts), `fill` (agent fills), or `research` (agent
-  fills with web search). When omitted, tools may infer from field roles or require
-  explicit selection. This is a hint for tooling, not enforced by the engine.
+- `run_mode` (*recommended*): Suggests how CLI tools should execute this form.
+  Values: `interactive` (user fills via prompts), `fill` (agent fills), or `research`
+  (agent fills with web search).
+  When omitted, tools may infer from field roles or require explicit selection.
+  This is a hint for tooling, not enforced by the engine.
 
 **Behavioral rules (*required*):**
 
@@ -211,8 +212,8 @@ Markform defines its own scoping rules where option IDs are field-scoped.
 Custom tags are defined following [Markdoc tag conventions][markdoc-tags]. See
 [Markdoc Config][markdoc-config] for how to register custom tags.
 
-All fields use the unified `{% field kind="..." %}` syntax. The `kind` attribute
-identifies what type of field a `Field` or `FieldValue` represents.
+All fields use the unified `{% field kind="..." %}` syntax.
+The `kind` attribute identifies what type of field a `Field` or `FieldValue` represents.
 (In TypeScript, the type is `FieldKind`.)
 
 | Kind | Description |
@@ -254,8 +255,9 @@ to different actors.
 | `placeholder` | string | Hint text shown in empty fields (displayed in UI) |
 | `examples` | string[] | Example values for the field (helps LLMs, shown in prompts) |
 
-These attributes are only valid on text-entry field kinds. Using them on chooser fields
-(single-select, multi-select, checkboxes) will result in a parse error.
+These attributes are only valid on text-entry field kinds.
+Using them on chooser fields (single-select, multi-select, checkboxes) will result in a
+parse error.
 
 **Example with placeholder and examples:**
 ```md
@@ -299,7 +301,8 @@ compatibility:
 | `multi_select` | `[x]` | Selected | `- [x] Option {% #opt_id %}` |
 
 **Note:** `single_select` enforces that exactly one option has `[x]`. The distinction
-between `single_select` and `multi_select` is in the `kind` attribute, not the marker syntax.
+between `single_select` and `multi_select` is in the `kind` attribute, not the marker
+syntax.
 
 The `{% #id %}` annotation **is** native Markdoc syntax (see
 [Attributes][markdoc-attributes]).
@@ -464,8 +467,8 @@ columnTypes=[{type: "string", required: true}, "number", "url"]
 {% /field %}
 ```
 
-**Sentinel values in table cells:**
-Cells can use `%SKIP%` and `%ABORT%` sentinels with optional reasons:
+**Sentinel values in table cells:** Cells can use `%SKIP%` and `%ABORT%` sentinels with
+optional reasons:
 ```md
 | 2017 | I, Tonya | 90 | %SKIP% (Box office not tracked) |
 ```
@@ -906,8 +909,8 @@ ACME
 {% /field %} {% field kind="string" id="fiscal_period" label="Fiscal period"
 required=true %}{% /field %} {% /group %}
 
-{% group id="source_docs" title="Source Documents" %} {% checkboxes
-id="docs_reviewed" label="Documents reviewed" required=true %}
+{% group id="source_docs" title="Source Documents" %} {% checkboxes id="docs_reviewed"
+label="Documents reviewed" required=true %}
 
 - [x] 10-K {% #ten_k %}
 
@@ -915,8 +918,7 @@ id="docs_reviewed" label="Documents reviewed" required=true %}
 
 - [/] Earnings release {% #earnings_release %}
 
-- [ ] Earnings call transcript {% #call_transcript %} {% /field %} {% /group
-  %}
+- [ ] Earnings call transcript {% #call_transcript %} {% /field %} {% /group %}
 ````
 
 Notes:
@@ -1859,7 +1861,7 @@ YAML keys use snake_case for readability and consistency with common YAML conven
 | TypeScript kind | `'string_list'` |
 | Attributes | `id`, `label`, `required`, `minItems`, `maxItems`, `itemMinLength`, `itemMaxLength`, `uniqueItems` |
 | FieldValue | `{ kind: 'string_list'; items: string[] }` |
-| Patch operation | `{ op: 'set_string_list'; fieldId: Id; items: string[] }` |
+| Patch operation | `{ op: 'set_string_list'; fieldId: Id; value: string[] }` |
 | Zod | `z.array(z.string().min(itemMin).max(itemMax)).min(n).max(m)` |
 | JSON Schema | `{ type: "array", items: { type: "string" }, minItems, maxItems, uniqueItems }` |
 
@@ -1872,7 +1874,7 @@ YAML keys use snake_case for readability and consistency with common YAML conven
 | TypeScript kind | `'single_select'` |
 | Attributes | `id`, `label`, `required` + inline `options` via list syntax |
 | FieldValue | `{ kind: 'single_select'; selected: OptionId \| null }` |
-| Patch operation | `{ op: 'set_single_select'; fieldId: Id; selected: OptionId \| null }` |
+| Patch operation | `{ op: 'set_single_select'; fieldId: Id; value: OptionId \| null }` |
 | Zod | `z.enum([...optionIds])` |
 | JSON Schema | `{ type: "string", enum: [...optionIds] }` |
 
@@ -1885,7 +1887,7 @@ YAML keys use snake_case for readability and consistency with common YAML conven
 | TypeScript kind | `'multi_select'` |
 | Attributes | `id`, `label`, `required`, `minSelections`, `maxSelections` + inline `options` |
 | FieldValue | `{ kind: 'multi_select'; selected: OptionId[] }` |
-| Patch operation | `{ op: 'set_multi_select'; fieldId: Id; selected: OptionId[] }` |
+| Patch operation | `{ op: 'set_multi_select'; fieldId: Id; value: OptionId[] }` |
 | Zod | `z.array(z.enum([...optionIds])).min(n).max(m)` |
 | JSON Schema | `{ type: "array", items: { enum: [...optionIds] }, minItems, maxItems }` |
 
@@ -1898,7 +1900,7 @@ YAML keys use snake_case for readability and consistency with common YAML conven
 | TypeScript kind | `'checkboxes'` |
 | Attributes | `id`, `label`, `required`, `checkboxMode` (`multi`/`simple`/`explicit`), `minDone` (simple only) + inline `options` |
 | FieldValue | `{ kind: 'checkboxes'; values: Record<OptionId, CheckboxValue> }` |
-| Patch operation | `{ op: 'set_checkboxes'; fieldId: Id; values: Record<OptionId, CheckboxValue> }` |
+| Patch operation | `{ op: 'set_checkboxes'; fieldId: Id; value: Record<OptionId, CheckboxValue> }` |
 | Zod | `z.record(z.enum([...states]))` |
 | JSON Schema | `{ type: "object", additionalProperties: { enum: [...states] } }` |
 
@@ -1924,7 +1926,7 @@ YAML keys use snake_case for readability and consistency with common YAML conven
 | TypeScript kind | `'url_list'` |
 | Attributes | `id`, `label`, `required`, `minItems`, `maxItems`, `uniqueItems` |
 | FieldValue | `{ kind: 'url_list'; items: string[] }` |
-| Patch operation | `{ op: 'set_url_list'; fieldId: Id; items: string[] }` |
+| Patch operation | `{ op: 'set_url_list'; fieldId: Id; value: string[] }` |
 | Zod | `z.array(z.url()).min(n).max(m)` |
 | JSON Schema | `{ type: "array", items: { type: "string", format: "uri" }, minItems, maxItems, uniqueItems }` |
 
@@ -1963,7 +1965,7 @@ YAML keys use snake_case for readability and consistency with common YAML conven
 | TypeScript kind | `'table'` |
 | Attributes | `id`, `label`, `required`, `columnIds`, `columnLabels`, `columnTypes`, `minRows`, `maxRows` |
 | FieldValue | `{ kind: 'table'; rows: TableRowResponse[] }` |
-| Patch operation | `{ op: 'set_table'; fieldId: Id; rows: PatchTableRow[] }` |
+| Patch operation | `{ op: 'set_table'; fieldId: Id; value: PatchTableRow[] }` |
 | Zod | `z.object({ kind: z.literal('table'), rows: z.array(TableRowResponseSchema) })` |
 | JSON Schema | `{ type: "object", properties: { kind: { const: "table" }, rows: { type: "array" } } }` |
 
@@ -2541,12 +2543,15 @@ This formula ensures:
 type Patch =
   | { op: 'set_string'; fieldId: Id; value: string | null }
   | { op: 'set_number'; fieldId: Id; value: number | null }
-  | { op: 'set_string_list'; fieldId: Id; items: string[] }
-  | { op: 'set_checkboxes'; fieldId: Id; values: Record<OptionId, CheckboxValue> }
-  | { op: 'set_single_select'; fieldId: Id; selected: OptionId | null }
-  | { op: 'set_multi_select'; fieldId: Id; selected: OptionId[] }
+  | { op: 'set_string_list'; fieldId: Id; value: string[] }
+  | { op: 'set_checkboxes'; fieldId: Id; value: Record<OptionId, CheckboxValue> }
+  | { op: 'set_single_select'; fieldId: Id; value: OptionId | null }
+  | { op: 'set_multi_select'; fieldId: Id; value: OptionId[] }
   | { op: 'set_url'; fieldId: Id; value: string | null }
-  | { op: 'set_url_list'; fieldId: Id; items: string[] }
+  | { op: 'set_url_list'; fieldId: Id; value: string[] }
+  | { op: 'set_table'; fieldId: Id; value: PatchTableRow[] }
+  | { op: 'set_date'; fieldId: Id; value: string | null }
+  | { op: 'set_year'; fieldId: Id; value: number | null }
   | { op: 'clear_field'; fieldId: Id }
   | { op: 'skip_field'; fieldId: Id; role: string; reason?: string }
   | { op: 'abort_field'; fieldId: Id; role: string; reason?: string }
@@ -2564,10 +2569,10 @@ Option IDs in patches are **local to the field** specified by `fieldId`. You do
 the qualified `{fieldId}.{optionId}` form in patches—the `fieldId` already provides the
 scope. For example:
 
-- `{ op: 'set_checkboxes', fieldId: 'docs_reviewed', values: { ten_k: 'done', ten_q:
+- `{ op: 'set_checkboxes', fieldId: 'docs_reviewed', value: { ten_k: 'done', ten_q:
   'done' } }`
 
-- `{ op: 'set_single_select', fieldId: 'rating', selected: 'bullish' }`
+- `{ op: 'set_single_select', fieldId: 'rating', value: 'bullish' }`
 
 **Patch semantics:**