markform 0.1.5 → 0.1.6

package/README.md

@@ -1,23 +1,57 @@
 # Markform
 
-***Structured Markdown documents for humans, agents, and APIs***
+**Markform** turns Markdown documents into executable specifications for structured data
+collection.
+Define fields, validation rules, and instructions in a single `.form.md` file
+that is readable by humans, parseable by machines, and fillable by LLM agents.
 
-**Markform** is a **file format**, **data model**, and **editing API** for
-**token-friendly, human-readable text forms**. Markform syntax is a superset of Markdown
-based on [Markdoc](https://github.com/markdoc/markdoc), stored as `.form.md` files.
+The core idea: **a form combines structure, unstructured context, and memory in a simple
+text document**. Users can give inputs via UIs or CLI. Agents can fill fields
+incrementally via tools or APIs.
+Validation catches errors early and humans can review or intervene at any point.
+The entire workflow is visible in a token-friendly text file you can read, diff, and
+version control.
 
-Markform is like if Markdown docs had a customizable API. The idea is to combine the
-simple utility of a Markdown document with structured tags that define typed fields and
-validation rules.
-Fields, validation rules, and instructions are encoded as Markdoc tags.
+Syntax is [Markdoc](https://github.com/markdoc/markdoc), which is Markdown extended with
+`{% tag %}` annotations, so LLMs are already quite good at writing Markform docs.
 
-Markform lets you build powerful agent workflows by structuring and validating *what*
-you want (the form structure and validations) instead of *how* to get it (coding up
-agent workflows). For deep research and other tasks where you want a high level of
-control on intermediate states and final output from an AI pipeline, this approach is a
-compelling alternative to programmatic or UI-based agent workflows.
-Because it’s just Markdown with tags, agents are also very good at writing Markform,
-which makes creating new workflows much easier.
+## Why?
+
+Many agent workflow frameworks emphasize *prompts* and the *flow* of information (the
+*how*) over the desired *structure* of the results (the *what*). Markform lets you build
+agent workflows by structuring and validating *what* you want (the structure of
+information, validations, and reviews encoded in a form) instead of *how* to run a
+workflow as code (via explicit workflows or just an unstructured swarm of agents).
+
+For centuries, humans have used paper forms to systematize and manage processes.
+A well-designed form with instructions, field definitions, and validations is a concise
+way to share context: background knowledge, goals, process rules, and memories.
+I don’t think AI changes this essential aspect of knowledge work.
+It’s time to bring bureaucracy to the agents.
+
+There’s one more key benefit to this approach: LLMs are good at writing forms!
+Because the syntax is just Markdown with Jinja-style tags, agents can convert an
+informal Markdown doc describing a process to a precise Markform process easily.
+
+(For more, see [the FAQ](#faq).)
+
+## Quick Start
+
+```bash
+# Try filling in one of a few example forms without installing.
+# First set OPENAI_API_KEY or ANTHROPIC_API_KEY in environment or .env file
+# to try the research examples.
+npx markform examples
+
+# Read the docs
+npx markform  # CLI help
+npx markform readme   # This file
+npx markform docs  # Quick start for humans or agents to write Markforms
+npx markform spec  # Read the full spec
+```
+
+This lets you walk through a form interactively from the CLI, with the option to have an
+agent fill in parts of the form.
 
 ## Installation
 
@@ -31,17 +65,6 @@ npm install -g markform
 npm install markform
 ```
 
-## Quick Start
-
-```bash
-# Try it without installing
-npx markform examples
-```
-
-This walks you through an example form interactively, with optional AI agent filling.
-You’ll need at least one [API key](#supported-providers) form a provider with a model
-that supports web search to have LLMs fill in forms.
-
 ## Example: Research a Movie
 
 ### Form Definition
@@ -156,38 +179,24 @@ Convicted banker Andy Dufresne is sent to Shawshank State Penitentiary, where he
 
 ### More Example Forms
 
-The package includes example forms in
-[`examples/`](https://github.com/jlevy/markform/tree/main/packages/markform/examples).
+The package includes example forms.
 View them with `markform examples --list` or try these interactively:
 
-- [`movie-research/movie-research-minimal.form.md`](https://github.com/jlevy/markform/blob/main/packages/markform/examples/movie-research/movie-research-minimal.form.md)
+- [`simple.form.md`](https://github.com/jlevy/markform/blob/main/packages/markform/examples/simple/simple.form.md)
+  \- Basic form demonstrating all field kinds.
+
+- [`movie-research-minimal.form.md`](https://github.com/jlevy/markform/blob/main/packages/markform/examples/movie-research/movie-research-minimal.form.md)
   \- The quick example above.
 
-- [`movie-research/movie-research-basic.form.md`](https://github.com/jlevy/markform/blob/main/packages/markform/examples/movie-research/movie-research-basic.form.md)
+- [`movie-research-basic.form.md`](https://github.com/jlevy/markform/blob/main/packages/markform/examples/movie-research/movie-research-basic.form.md)
   \- Standard movie research with IMDB, Rotten Tomatoes, Metacritic.
 
-- [`movie-research/movie-research-deep.form.md`](https://github.com/jlevy/markform/blob/main/packages/markform/examples/movie-research/movie-research-deep.form.md)
+- [`movie-research-deep.form.md`](https://github.com/jlevy/markform/blob/main/packages/markform/examples/movie-research/movie-research-deep.form.md)
   \- Comprehensive movie analysis with streaming, box office, analysis.
 
-- [`simple/simple.form.md`](https://github.com/jlevy/markform/blob/main/packages/markform/examples/simple/simple.form.md)
-  \- Basic form demonstrating all field kinds.
-
-- [`earnings-analysis/earnings-analysis.form.md`](https://github.com/jlevy/markform/blob/main/packages/markform/examples/earnings-analysis/earnings-analysis.form.md)
+- [`earnings-analysis.form.md`](https://github.com/jlevy/markform/blob/main/packages/markform/examples/earnings-analysis/earnings-analysis.form.md)
   \- Financial analysis form.
 
-## Why?
-
-Many agent workflow frameworks emphasize the *flow* of information (the *how*) over its
-*structure* (the *what*). But the *how* is constantly changing.
-
-What we often really want is to express *desired structure and validation rules* for
-content directly in a way that provides clear context to agents and humans at all times.
-
-Humans have for centuries used paper forms to systematize and manage processes.
-The key insight of Markform is that the most natural way to express the state and
-context for a workflow is often *forms*. Just as Markdown is a transparent format for
-documents, Markform is a transparent text format for structured information.
-
 ## CLI Commands
 
 ### Explore Examples
@@ -415,6 +424,19 @@ const result = await generateText({
 
 ## FAQ
 
+### Can you say more why this is a good idea?
+
+Yes! I’ve come to believe forms are a missing piece of the workflow problem with agents.
+For deep research or complex multi-step workflows, key pieces need to be *precisely
+controlled*, *domain-specific*, and *always improving*. You need precise documentation
+on the key intermediate states and final output from an AI pipeline.
+
+But you don’t want structure in a GUI (not token friendly) or code (hard to update) or
+dependent on the whims of a thinking model (changes all the time).
+Forms define these pieces and are easy to edit.
+All other choices can be left to the agents themselves, with the structure and
+validations enforced by the form-filling tools the agents use.
+
 ### Is this mature?
 
 No! I just wrote it.
@@ -467,7 +489,8 @@ This enables powerful AI workflows that assemble information in a defined struct
 
 ### Does anything like this already exist?
 
-Not really. The closest alternatives are:
+Not that I have seen.
+The closest alternatives are:
 
 - Plain Markdown docs can be used as templates and filled in by agents.
   These are more expressive, but it is hard to edit them programmatically or use LLMs to
@@ -481,13 +504,13 @@ Not really. The closest alternatives are:
   human-friendly UI. But these do not have a human-friendly text format for use by
   agents as well as humans.
 
-| Approach | Has GUI | Human-readable text format | Agent-editable | APIs and validation rules |
+| Approach | Has GUI | Human-readable source format | Agent-editable | APIs and validation rules |
 | --- | :---: | :---: | :---: | :---: |
 | Plain Markdown | ☑️ existing tools | ✅ | ⚠️ fragile | ❌ |
-| JSON with schema | ☑️ existing tools | ⚠️ hey it’s JSON | ✅ | ✅ |
+| JSON with schema | ⚠️ in some apps | ⚠️ um it’s JSON | ✅ | ✅ |
 | SaaS tools (Typeform, Docusign, PDF forms) | ✅ | ⚠️ rarely | ⚠️ if they add it | ⚠️ if they add it |
-| Excel/Google Sheets | ✅ | ❌ .xlsx | ⚠️ with tools | ✅ |
-| **Markform** | ☑️ existing tools | ✅ | ✅ | ✅ |
+| Excel/Google Sheets | ✅ | ❌ .csv (poor) or .xlsx (worse) | ⚠️ with tools | ✅ with some coding |
+| **Markform** | ☑️ existing tools | ✅ | ✅ with this package | ✅ with this package |
 
 ### What are example use cases?
 

package/dist/ai-sdk.mjs

@@ -1,5 +1,5 @@
 import { L as PatchSchema } from "./coreTypes-pyctKRgc.mjs";
-import { r as inspect, t as applyPatches, u as serialize } from "./apply-BCCiJzQr.mjs";
+import { r as inspect, t as applyPatches, u as serialize } from "./apply-DMQl-VVd.mjs";
 import { z } from "zod";
 
 //#region src/integrations/vercelAiSdkTools.ts

package/dist/{apply-BCCiJzQr.mjs → apply-DMQl-VVd.mjs}

@@ -1,5 +1,3 @@
-import { resolve } from "node:path";
-
 //#region src/llms.ts
 /**
 * Parse a model ID string into provider and model components for display.
@@ -113,13 +111,6 @@ function getWebSearchConfig(provider) {
 //#endregion
 //#region src/settings.ts
 /**
-* Global settings and constants for Markform.
-*
-* This file consolidates non-changing default values that were previously
-* scattered across the codebase. These are NOT runtime configurable - they
-* are compile-time constants.
-*/
-/**
 * The current Markform spec version in full notation (e.g., "MF/0.1").
 * This is distinct from npm package version and tracks the format that
 * .form.md files conform to.
@@ -165,25 +156,14 @@ function parseRolesFlag(raw) {
 */
 const DEFAULT_PRIORITY = "medium";
 /**
-* The default port for the serve command.
-*/
-const DEFAULT_PORT = 3344;
-/**
 * Default forms directory for CLI output (relative to cwd).
 * Commands write form outputs here to avoid cluttering the workspace.
 */
 const DEFAULT_FORMS_DIR = "./forms";
 /**
-* Resolve the forms directory path to an absolute path.
-* Uses the provided override or falls back to DEFAULT_FORMS_DIR.
-*
-* @param override Optional override path from CLI --forms-dir option
-* @param cwd Base directory for resolving relative paths (defaults to process.cwd())
-* @returns Absolute path to the forms directory
+* The default port for the serve command.
 */
-function getFormsDir(override, cwd = process.cwd()) {
-	return resolve(cwd, override ?? DEFAULT_FORMS_DIR);
-}
+const DEFAULT_PORT = 3344;
 /**
 * Default maximum turns for the fill harness.
 * Prevents runaway loops during agent execution.
@@ -2824,4 +2804,4 @@ function applyPatches(form, patches) {
 }
 
 //#endregion
-export { parseRolesFlag as A, DEFAULT_ROLE_INSTRUCTIONS as C, deriveReportPath as D, deriveExportPath as E, hasWebSearchSupport as F, parseModelIdForDisplay as I, WEB_SEARCH_CONFIG as M, formatSuggestedLlms as N, detectFileType as O, getWebSearchConfig as P, DEFAULT_ROLES as S, USER_ROLE as T, DEFAULT_MAX_TURNS as _, computeAllSummaries as a, DEFAULT_RESEARCH_MAX_ISSUES_PER_TURN as b, computeStructureSummary as c, serializeRawMarkdown as d, serializeReportMarkdown as f, DEFAULT_MAX_PATCHES_PER_TURN as g, DEFAULT_MAX_ISSUES_PER_TURN as h, validate as i, SUGGESTED_LLMS as j, getFormsDir as k, isFormComplete as l, DEFAULT_FORMS_DIR as m, getFieldsForRoles as n, computeFormState as o, AGENT_ROLE as p, inspect as r, computeProgressSummary as s, applyPatches as t, serialize as u, DEFAULT_PORT as v, REPORT_EXTENSION as w, DEFAULT_RESEARCH_MAX_PATCHES_PER_TURN as x, DEFAULT_PRIORITY as y };
+export { SUGGESTED_LLMS as A, DEFAULT_ROLE_INSTRUCTIONS as C, deriveReportPath as D, deriveExportPath as E, parseModelIdForDisplay as F, formatSuggestedLlms as M, getWebSearchConfig as N, detectFileType as O, hasWebSearchSupport as P, DEFAULT_ROLES as S, USER_ROLE as T, DEFAULT_MAX_TURNS as _, computeAllSummaries as a, DEFAULT_RESEARCH_MAX_ISSUES_PER_TURN as b, computeStructureSummary as c, serializeRawMarkdown as d, serializeReportMarkdown as f, DEFAULT_MAX_PATCHES_PER_TURN as g, DEFAULT_MAX_ISSUES_PER_TURN as h, validate as i, WEB_SEARCH_CONFIG as j, parseRolesFlag as k, isFormComplete as l, DEFAULT_FORMS_DIR as m, getFieldsForRoles as n, computeFormState as o, AGENT_ROLE as p, inspect as r, computeProgressSummary as s, applyPatches as t, serialize as u, DEFAULT_PORT as v, REPORT_EXTENSION as w, DEFAULT_RESEARCH_MAX_PATCHES_PER_TURN as x, DEFAULT_PRIORITY as y };

package/dist/bin.mjs

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 import "./coreTypes-pyctKRgc.mjs";
-import "./apply-BCCiJzQr.mjs";
-import "./src-Df0XX7UB.mjs";
+import "./apply-DMQl-VVd.mjs";
+import "./src-o_5TSoHQ.mjs";
 import "./session-uF0e6m6k.mjs";
-import "./shared-BqPnYXrn.mjs";
-import { t as runCli } from "./cli-D469amuk.mjs";
+import { t as runCli } from "./cli-CXjkdym_.mjs";
+import "./shared-DRlgu2ZJ.mjs";
 import { resolve } from "node:path";
 import { existsSync } from "node:fs";
 import { config } from "dotenv";

package/dist/{cli-D469amuk.mjs → cli-CXjkdym_.mjs}

@@ -1,12 +1,12 @@
 import { L as PatchSchema } from "./coreTypes-pyctKRgc.mjs";
-import { A as parseRolesFlag, D as deriveReportPath, E as deriveExportPath, F as hasWebSearchSupport, I as parseModelIdForDisplay, M as WEB_SEARCH_CONFIG, N as formatSuggestedLlms, O as detectFileType, T as USER_ROLE, _ as DEFAULT_MAX_TURNS, b as DEFAULT_RESEARCH_MAX_ISSUES_PER_TURN, d as serializeRawMarkdown, f as serializeReportMarkdown, g as DEFAULT_MAX_PATCHES_PER_TURN, h as DEFAULT_MAX_ISSUES_PER_TURN, j as SUGGESTED_LLMS, k as getFormsDir, m as DEFAULT_FORMS_DIR, p as AGENT_ROLE, r as inspect, t as applyPatches, u as serialize, v as DEFAULT_PORT, w as REPORT_EXTENSION, x as DEFAULT_RESEARCH_MAX_PATCHES_PER_TURN } from "./apply-BCCiJzQr.mjs";
-import { a as resolveHarnessConfig, c as getProviderNames, f as createMockAgent, i as runResearch, l as resolveModel, m as createHarness, s as getProviderInfo, t as VERSION, u as createLiveAgent, w as parseForm } from "./src-Df0XX7UB.mjs";
+import { A as SUGGESTED_LLMS, D as deriveReportPath, E as deriveExportPath, F as parseModelIdForDisplay, M as formatSuggestedLlms, O as detectFileType, P as hasWebSearchSupport, T as USER_ROLE, _ as DEFAULT_MAX_TURNS, b as DEFAULT_RESEARCH_MAX_ISSUES_PER_TURN, d as serializeRawMarkdown, f as serializeReportMarkdown, g as DEFAULT_MAX_PATCHES_PER_TURN, h as DEFAULT_MAX_ISSUES_PER_TURN, j as WEB_SEARCH_CONFIG, k as parseRolesFlag, m as DEFAULT_FORMS_DIR, p as AGENT_ROLE, r as inspect, t as applyPatches, u as serialize, v as DEFAULT_PORT, w as REPORT_EXTENSION, x as DEFAULT_RESEARCH_MAX_PATCHES_PER_TURN } from "./apply-DMQl-VVd.mjs";
+import { a as resolveHarnessConfig, c as getProviderNames, f as createMockAgent, i as runResearch, l as resolveModel, m as createHarness, s as getProviderInfo, t as VERSION, u as createLiveAgent, w as parseForm } from "./src-o_5TSoHQ.mjs";
 import { n as serializeSession } from "./session-uF0e6m6k.mjs";
-import { a as formatPath, c as logError, d as logTiming, f as logVerbose, g as writeFile, i as formatOutput, l as logInfo, m as readFile$1, n as createSpinner, o as getCommandContext, p as logWarn, r as ensureFormsDir, s as logDryRun, t as OUTPUT_FORMATS, u as logSuccess } from "./shared-BqPnYXrn.mjs";
+import { a as formatPath, c as logError, d as logTiming, f as logVerbose, g as writeFile, i as formatOutput, l as logInfo, m as readFile$1, n as createSpinner, o as getCommandContext, p as logWarn, r as ensureFormsDir, s as logDryRun, t as OUTPUT_FORMATS, u as logSuccess } from "./shared-DRlgu2ZJ.mjs";
 import YAML from "yaml";
-import { basename, dirname, join, resolve } from "node:path";
 import { Command } from "commander";
 import pc from "picocolors";
+import { basename, dirname, join, resolve } from "node:path";
 import { existsSync, readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { readFile } from "node:fs/promises";
@@ -14,6 +14,27 @@ import * as p from "@clack/prompts";
 import { exec, spawn } from "node:child_process";
 import { createServer } from "node:http";
 
+//#region src/cli/lib/paths.ts
+/**
+* Path utilities for CLI commands.
+*
+* This module contains Node.js-dependent path utilities that are only used
+* by CLI code. Keeping these separate from settings.ts allows the core
+* library to remain Node.js-free.
+*/
+/**
+* Resolve the forms directory path to an absolute path.
+* Uses the provided override or falls back to DEFAULT_FORMS_DIR.
+*
+* @param override Optional override path from CLI --forms-dir option
+* @param cwd Base directory for resolving relative paths (defaults to process.cwd())
+* @returns Absolute path to the forms directory
+*/
+function getFormsDir(override, cwd = process.cwd()) {
+	return resolve(cwd, override ?? DEFAULT_FORMS_DIR);
+}
+
+//#endregion
 //#region src/cli/commands/apis.ts
 /**
 * Get the path to the markform-apis.md file.
@@ -2101,6 +2122,39 @@ function registerExportCommand(program) {
 	});
 }
 
+//#endregion
+//#region src/cli/lib/fillCallbacks.ts
+/**
+* Create FillCallbacks for CLI commands.
+*
+* Provides spinner feedback during tool execution (especially web search).
+* Only implements tool callbacks - turn/LLM callbacks are handled by CLI's
+* own logging which has richer context.
+*
+* @param spinner - Active spinner handle to update
+* @param ctx - Command context for verbose logging
+* @returns FillCallbacks with onToolStart and onToolEnd
+*
+* @example
+* ```typescript
+* const spinner = createSpinner({ type: 'api', provider, model });
+* const callbacks = createCliToolCallbacks(spinner, ctx);
+* const agent = createLiveAgent({ model, callbacks, ... });
+* ```
+*/
+function createCliToolCallbacks(spinner, ctx) {
+	return {
+		onToolStart: ({ name }) => {
+			if (name.includes("search")) spinner.message(`🔍 Web search...`);
+			logVerbose(ctx, `  Tool started: ${name}`);
+		},
+		onToolEnd: ({ name, durationMs, error }) => {
+			if (error) logVerbose(ctx, `  Tool ${name} failed: ${error} (${durationMs}ms)`);
+			else logVerbose(ctx, `  Tool ${name} completed (${durationMs}ms)`);
+		}
+	};
+}
+
 //#endregion
 //#region src/cli/commands/fill.ts
 /**
@@ -2243,6 +2297,7 @@ function registerFillCommand(program) {
 			let mockPath;
 			let agentProvider;
 			let agentModelName;
+			let currentSpinner = null;
 			if (options.mock) {
 				mockPath = resolve(options.mockSource);
 				logVerbose(ctx, `Reading mock source: ${mockPath}`);
@@ -2262,13 +2317,21 @@ function registerFillCommand(program) {
 					logVerbose(ctx, `Reading system prompt from: ${promptPath}`);
 					systemPrompt = await readFile$1(promptPath);
 				}
+				const callbacks = createCliToolCallbacks({
+					message: (msg) => currentSpinner?.message(msg),
+					update: (context) => currentSpinner?.update(context),
+					stop: (msg) => currentSpinner?.stop(msg),
+					error: (msg) => currentSpinner?.error(msg),
+					getElapsedMs: () => currentSpinner?.getElapsedMs() ?? 0
+				}, ctx);
 				const primaryRole = targetRoles[0] === "*" ? AGENT_ROLE : targetRoles[0];
 				const liveAgent = createLiveAgent({
 					model,
 					provider,
 					systemPromptAddition: systemPrompt,
 					targetRole: primaryRole,
-					enableWebSearch: true
+					enableWebSearch: true,
+					callbacks
 				});
 				agent = liveAgent;
 				logInfo(ctx, `Available tools: ${liveAgent.getAvailableToolNames().join(", ")}`);
@@ -2285,18 +2348,23 @@ function registerFillCommand(program) {
 			logInfo(ctx, `${pc.bold(`Turn ${stepResult.turnNumber}:`)} ${formatTurnIssues(stepResult.issues)}`);
 			while (!stepResult.isComplete && !harness.hasReachedMaxTurns()) {
 				let spinner = null;
-				if (!options.mock && agentProvider && agentModelName && process.stdout.isTTY && !ctx.quiet) spinner = createSpinner({
-					type: "api",
-					provider: agentProvider,
-					model: agentModelName,
-					turnNumber: stepResult.turnNumber
-				});
+				if (!options.mock && agentProvider && agentModelName && process.stdout.isTTY && !ctx.quiet) {
+					spinner = createSpinner({
+						type: "api",
+						provider: agentProvider,
+						model: agentModelName,
+						turnNumber: stepResult.turnNumber
+					});
+					currentSpinner = spinner;
+				}
 				let response;
 				try {
 					response = await agent.generatePatches(stepResult.issues, harness.getForm(), harnessConfig.maxPatchesPerTurn);
 					spinner?.stop();
+					currentSpinner = null;
 				} catch (error) {
 					spinner?.error("LLM call failed");
+					currentSpinner = null;
 					throw error;
 				}
 				const { patches, stats } = response;
@@ -4037,7 +4105,7 @@ function registerResearchCommand(program) {
 			if (options.transcript && result.transcript) {
 				const { serializeSession: serializeSession$1 } = await import("./session-B_stoXQn.mjs");
 				const transcriptPath = outputPath.replace(/\.form\.md$/, ".session.yaml");
-				const { writeFile: writeFile$1 } = await import("./shared-CZsyShck.mjs");
+				const { writeFile: writeFile$1 } = await import("./shared-u22MtBRo.mjs");
 				await writeFile$1(transcriptPath, serializeSession$1(result.transcript));
 				logInfo(ctx, `Transcript: ${transcriptPath}`);
 			}

package/dist/cli.mjs

@@ -1,8 +1,8 @@
 import "./coreTypes-pyctKRgc.mjs";
-import "./apply-BCCiJzQr.mjs";
-import "./src-Df0XX7UB.mjs";
+import "./apply-DMQl-VVd.mjs";
+import "./src-o_5TSoHQ.mjs";
 import "./session-uF0e6m6k.mjs";
-import "./shared-BqPnYXrn.mjs";
-import { t as runCli } from "./cli-D469amuk.mjs";
+import { t as runCli } from "./cli-CXjkdym_.mjs";
+import "./shared-DRlgu2ZJ.mjs";
 
 export { runCli };

package/dist/index.d.mts

@@ -519,6 +519,57 @@ interface Agent {
    */
   generatePatches(issues: InspectIssue[], form: ParsedForm, maxPatches: number): Promise<AgentResponse>;
 }
+/**
+ * Callbacks for observing form-filling execution in real-time.
+ *
+ * All callbacks are optional - implement only what you need.
+ * Callback errors are caught and ignored (won't abort fill).
+ *
+ * @example
+ * ```typescript
+ * await fillForm({
+ *   form: formMarkdown,
+ *   model: 'anthropic/claude-sonnet-4-5',
+ *   enableWebSearch: true,
+ *   callbacks: {
+ *     onTurnStart: ({ turnNumber }) => console.log(`Starting turn ${turnNumber}`),
+ *     onToolStart: ({ name }) => spinner.message(`🔧 ${name}...`),
+ *     onTurnComplete: (progress) => console.log(`Turn ${progress.turnNumber} done`),
+ *   },
+ * });
+ * ```
+ */
+interface FillCallbacks {
+  /** Called when a turn begins */
+  onTurnStart?(turn: {
+    turnNumber: number;
+    issuesCount: number;
+  }): void;
+  /** Called when a turn completes */
+  onTurnComplete?(progress: TurnProgress): void;
+  /** Called before a tool executes */
+  onToolStart?(call: {
+    name: string;
+    input: unknown;
+  }): void;
+  /** Called after a tool completes */
+  onToolEnd?(call: {
+    name: string;
+    output: unknown;
+    durationMs: number;
+    error?: string;
+  }): void;
+  /** Called before an LLM request */
+  onLlmCallStart?(call: {
+    model: string;
+  }): void;
+  /** Called after an LLM response */
+  onLlmCallEnd?(call: {
+    model: string;
+    inputTokens: number;
+    outputTokens: number;
+  }): void;
+}
 /**
  * Options for the fillForm function.
  */
@@ -544,8 +595,8 @@ interface FillOptions {
   targetRoles?: string[];
   /** Fill mode: 'continue' (skip filled) or 'overwrite' (re-fill) */
   fillMode?: FillMode;
-  /** Progress callback called after each turn */
-  onTurnComplete?: (progress: TurnProgress) => void;
+  /** Callbacks for observing form-filling execution */
+  callbacks?: FillCallbacks;
   /** AbortSignal for cancellation */
   signal?: AbortSignal;
   /**
@@ -673,6 +724,7 @@ declare function createMockAgent(completedForm: ParsedForm): MockAgent;
  * const result = await fillForm({
  *   form: formMarkdown,
  *   model: 'anthropic/claude-sonnet-4-5',
+ *   enableWebSearch: true,
  *   inputContext: {
  *     company_name: 'Apple Inc.',
  *   },
@@ -680,8 +732,10 @@ declare function createMockAgent(completedForm: ParsedForm): MockAgent;
  *     ## Additional Context
  *     ${backgroundInfo}
  *   `,
- *   onTurnComplete: (progress) => {
- *     console.log(`Turn ${progress.turnNumber}: ${progress.requiredIssuesRemaining} remaining`);
+ *   callbacks: {
+ *     onTurnComplete: (progress) => {
+ *       console.log(`Turn ${progress.turnNumber}: ${progress.requiredIssuesRemaining} remaining`);
+ *     },
  *   },
  * });
  *
@@ -791,7 +845,7 @@ declare function validateResearchForm(form: ParsedForm): {
  * This is the main library entry point that exports the core engine,
  * types, and utilities for working with .form.md files.
  */
-/** Markform version (read from package.json). */
+/** Markform version (injected at build time). */
 declare const VERSION: string;
 //#endregion
-export { type AgentResponse, type AnswerState, AnswerStateSchema, type ApplyResult, ApplyResultSchema, type CellResponse, CellResponseSchema, type CellScopeRef, type CheckboxMode, CheckboxModeSchema, type CheckboxProgressCounts, CheckboxProgressCountsSchema, type CheckboxValue, CheckboxValueSchema, type CheckboxesField, CheckboxesFieldSchema, type CheckboxesValue, CheckboxesValueSchema, type ClearFieldPatch, ClearFieldPatchSchema, type CoerceInputContextResult, type CoercionResult, type ColumnTypeName, ColumnTypeNameSchema, type ComputedSummaries, type DateField, DateFieldSchema, type DateValue, DateValueSchema, type DocumentationBlock, DocumentationBlockSchema, type DocumentationTag, DocumentationTagSchema, type ExplicitCheckboxValue, ExplicitCheckboxValueSchema, type Field, type FieldBase, type FieldGroup, FieldGroupSchema, type FieldKind, FieldKindSchema, type FieldProgress, FieldProgressSchema, type FieldResponse, FieldResponseSchema, FieldSchema, type FieldScopeRef, type FieldValue, FieldValueSchema, type FillOptions, type FillResult, type FillStatus, FormHarness, type FormSchema, FormSchemaSchema, type FrontmatterHarnessConfig, type HarnessConfig, HarnessConfigSchema, type Id, type IdIndexEntry, IdSchema, type InputContext, type InspectIssue, InspectIssueSchema, type InspectOptions, type InspectResult, InspectResultSchema, type IssueReason, IssueReasonSchema, type IssueScope, IssueScopeSchema, type MarkformFrontmatter, MarkformFrontmatterSchema, MockAgent, type MultiCheckboxState, MultiCheckboxStateSchema, type MultiSelectField, MultiSelectFieldSchema, type MultiSelectValue, MultiSelectValueSchema, type NodeType, type NumberField, NumberFieldSchema, type NumberValue, NumberValueSchema, type Option, type OptionId, OptionIdSchema, OptionSchema, ParseError, type ParseScopeRefResult, type ParseTableResult, type ParsedForm, type ParsedRawTable, type ParsedScopeRef, type Patch, PatchSchema, type ProgressCounts, ProgressCountsSchema, type ProgressState, ProgressStateSchema, type ProgressSummary, ProgressSummarySchema, type QualifiedColumnRef, type QualifiedOptionRef, type QualifiedScopeRef, type RawFieldValue, type ResearchOptions, type ResearchResult, type ResearchStatus, type SerializeOptions, type SessionFinal, SessionFinalSchema, type SessionTranscript, SessionTranscriptSchema, type SessionTurn, SessionTurnSchema, type SessionTurnStats, type SetCheckboxesPatch, SetCheckboxesPatchSchema, type SetDatePatch, SetDatePatchSchema, type SetMultiSelectPatch, SetMultiSelectPatchSchema, type SetNumberPatch, SetNumberPatchSchema, type SetSingleSelectPatch, SetSingleSelectPatchSchema, type SetStringListPatch, SetStringListPatchSchema, type SetStringPatch, SetStringPatchSchema, type SetTablePatch, SetTablePatchSchema, type SetUrlListPatch, SetUrlListPatchSchema, type SetUrlPatch, SetUrlPatchSchema, type SetYearPatch, SetYearPatchSchema, type Severity, SeveritySchema, type SimpleCheckboxState, SimpleCheckboxStateSchema, type SingleSelectField, SingleSelectFieldSchema, type SingleSelectValue, SingleSelectValueSchema, type SourcePosition, SourcePositionSchema, type SourceRange, SourceRangeSchema, type StepResult, StepResultSchema, type StringField, StringFieldSchema, type StringListField, StringListFieldSchema, type StringListValue, StringListValueSchema, type StringValue, StringValueSchema, type StructureSummary, StructureSummarySchema, type TableColumn, TableColumnSchema, type TableField, TableFieldSchema, type TableRowPatch, TableRowPatchSchema, type TableRowResponse, TableRowResponseSchema, type TableValue, TableValueSchema, type TurnProgress, type TurnStats, type UrlField, UrlFieldSchema, type UrlListField, UrlListFieldSchema, type UrlListValue, UrlListValueSchema, type UrlValue, UrlValueSchema, VERSION, type ValidateOptions, type ValidateResult, type ValidationIssue, ValidationIssueSchema, type ValidatorContext, type ValidatorFn, type ValidatorRef, ValidatorRefSchema, type ValidatorRegistry, type YearField, YearFieldSchema, type YearValue, YearValueSchema, applyPatches, coerceInputContext, coerceToFieldPatch, computeAllSummaries, computeFormState, computeProgressSummary, computeStructureSummary, createHarness, createMockAgent, fillForm, findFieldById, getFieldId, inspect, isCellRef, isFieldRef, isFormComplete, isQualifiedRef, isResearchForm, parseCellValue, parseForm, parseMarkdownTable, parseRawTable, parseScopeRef, parseSession, resolveHarnessConfig, runResearch, serialize, serializeScopeRef, serializeSession, validate, validateResearchForm };
+export { type AgentResponse, type AnswerState, AnswerStateSchema, type ApplyResult, ApplyResultSchema, type CellResponse, CellResponseSchema, type CellScopeRef, type CheckboxMode, CheckboxModeSchema, type CheckboxProgressCounts, CheckboxProgressCountsSchema, type CheckboxValue, CheckboxValueSchema, type CheckboxesField, CheckboxesFieldSchema, type CheckboxesValue, CheckboxesValueSchema, type ClearFieldPatch, ClearFieldPatchSchema, type CoerceInputContextResult, type CoercionResult, type ColumnTypeName, ColumnTypeNameSchema, type ComputedSummaries, type DateField, DateFieldSchema, type DateValue, DateValueSchema, type DocumentationBlock, DocumentationBlockSchema, type DocumentationTag, DocumentationTagSchema, type ExplicitCheckboxValue, ExplicitCheckboxValueSchema, type Field, type FieldBase, type FieldGroup, FieldGroupSchema, type FieldKind, FieldKindSchema, type FieldProgress, FieldProgressSchema, type FieldResponse, FieldResponseSchema, FieldSchema, type FieldScopeRef, type FieldValue, FieldValueSchema, type FillCallbacks, type FillOptions, type FillResult, type FillStatus, FormHarness, type FormSchema, FormSchemaSchema, type FrontmatterHarnessConfig, type HarnessConfig, HarnessConfigSchema, type Id, type IdIndexEntry, IdSchema, type InputContext, type InspectIssue, InspectIssueSchema, type InspectOptions, type InspectResult, InspectResultSchema, type IssueReason, IssueReasonSchema, type IssueScope, IssueScopeSchema, type MarkformFrontmatter, MarkformFrontmatterSchema, MockAgent, type MultiCheckboxState, MultiCheckboxStateSchema, type MultiSelectField, MultiSelectFieldSchema, type MultiSelectValue, MultiSelectValueSchema, type NodeType, type NumberField, NumberFieldSchema, type NumberValue, NumberValueSchema, type Option, type OptionId, OptionIdSchema, OptionSchema, ParseError, type ParseScopeRefResult, type ParseTableResult, type ParsedForm, type ParsedRawTable, type ParsedScopeRef, type Patch, PatchSchema, type ProgressCounts, ProgressCountsSchema, type ProgressState, ProgressStateSchema, type ProgressSummary, ProgressSummarySchema, type QualifiedColumnRef, type QualifiedOptionRef, type QualifiedScopeRef, type RawFieldValue, type ResearchOptions, type ResearchResult, type ResearchStatus, type SerializeOptions, type SessionFinal, SessionFinalSchema, type SessionTranscript, SessionTranscriptSchema, type SessionTurn, SessionTurnSchema, type SessionTurnStats, type SetCheckboxesPatch, SetCheckboxesPatchSchema, type SetDatePatch, SetDatePatchSchema, type SetMultiSelectPatch, SetMultiSelectPatchSchema, type SetNumberPatch, SetNumberPatchSchema, type SetSingleSelectPatch, SetSingleSelectPatchSchema, type SetStringListPatch, SetStringListPatchSchema, type SetStringPatch, SetStringPatchSchema, type SetTablePatch, SetTablePatchSchema, type SetUrlListPatch, SetUrlListPatchSchema, type SetUrlPatch, SetUrlPatchSchema, type SetYearPatch, SetYearPatchSchema, type Severity, SeveritySchema, type SimpleCheckboxState, SimpleCheckboxStateSchema, type SingleSelectField, SingleSelectFieldSchema, type SingleSelectValue, SingleSelectValueSchema, type SourcePosition, SourcePositionSchema, type SourceRange, SourceRangeSchema, type StepResult, StepResultSchema, type StringField, StringFieldSchema, type StringListField, StringListFieldSchema, type StringListValue, StringListValueSchema, type StringValue, StringValueSchema, type StructureSummary, StructureSummarySchema, type TableColumn, TableColumnSchema, type TableField, TableFieldSchema, type TableRowPatch, TableRowPatchSchema, type TableRowResponse, TableRowResponseSchema, type TableValue, TableValueSchema, type TurnProgress, type TurnStats, type UrlField, UrlFieldSchema, type UrlListField, UrlListFieldSchema, type UrlListValue, UrlListValueSchema, type UrlValue, UrlValueSchema, VERSION, type ValidateOptions, type ValidateResult, type ValidationIssue, ValidationIssueSchema, type ValidatorContext, type ValidatorFn, type ValidatorRef, ValidatorRefSchema, type ValidatorRegistry, type YearField, YearFieldSchema, type YearValue, YearValueSchema, applyPatches, coerceInputContext, coerceToFieldPatch, computeAllSummaries, computeFormState, computeProgressSummary, computeStructureSummary, createHarness, createMockAgent, fillForm, findFieldById, getFieldId, inspect, isCellRef, isFieldRef, isFormComplete, isQualifiedRef, isResearchForm, parseCellValue, parseForm, parseMarkdownTable, parseRawTable, parseScopeRef, parseSession, resolveHarnessConfig, runResearch, serialize, serializeScopeRef, serializeSession, validate, validateResearchForm };

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import { $ as SetUrlPatchSchema, A as MultiCheckboxStateSchema, B as ProgressSummarySchema, C as HarnessConfigSchema, Ct as ValidatorRefSchema, D as IssueReasonSchema, E as InspectResultSchema, F as OptionIdSchema, G as SetDatePatchSchema, H as SessionTranscriptSchema, I as OptionSchema, J as SetSingleSelectPatchSchema, K as SetMultiSelectPatchSchema, L as PatchSchema, M as MultiSelectValueSchema, N as NumberFieldSchema, O as IssueScopeSchema, P as NumberValueSchema, Q as SetUrlListPatchSchema, R as ProgressCountsSchema, S as FormSchemaSchema, St as ValidationIssueSchema, T as InspectIssueSchema, Tt as YearValueSchema, U as SessionTurnSchema, V as SessionFinalSchema, W as SetCheckboxesPatchSchema, X as SetStringPatchSchema, Y as SetStringListPatchSchema, Z as SetTablePatchSchema, _ as FieldKindSchema, _t as TableValueSchema, a as CheckboxProgressCountsSchema, at as SourcePositionSchema, b as FieldSchema, bt as UrlListValueSchema, c as CheckboxesValueSchema, ct as StringFieldSchema, d as DateFieldSchema, dt as StringValueSchema, et as SetYearPatchSchema, f as DateValueSchema, ft as StructureSummarySchema, g as FieldGroupSchema, gt as TableRowResponseSchema, h as ExplicitCheckboxValueSchema, ht as TableRowPatchSchema, i as CheckboxModeSchema, it as SingleSelectValueSchema, j as MultiSelectFieldSchema, k as MarkformFrontmatterSchema, l as ClearFieldPatchSchema, lt as StringListFieldSchema, m as DocumentationTagSchema, mt as TableFieldSchema, n as ApplyResultSchema, nt as SimpleCheckboxStateSchema, o as CheckboxValueSchema, ot as SourceRangeSchema, p as DocumentationBlockSchema, pt as TableColumnSchema, q as SetNumberPatchSchema, r as CellResponseSchema, rt as SingleSelectFieldSchema, s as CheckboxesFieldSchema, st as StepResultSchema, t as AnswerStateSchema, tt as SeveritySchema, u as ColumnTypeNameSchema, ut as StringListValueSchema, v as FieldProgressSchema, vt as UrlFieldSchema, w as IdSchema, wt as YearFieldSchema, x as FieldValueSchema, xt as UrlValueSchema, y as FieldResponseSchema, yt as UrlListFieldSchema, z as ProgressStateSchema } from "./coreTypes-pyctKRgc.mjs";
-import { a as computeAllSummaries, c as computeStructureSummary, i as validate, l as isFormComplete, o as computeFormState, r as inspect, s as computeProgressSummary, t as applyPatches, u as serialize } from "./apply-BCCiJzQr.mjs";
-import { C as serializeScopeRef, D as parseRawTable, E as parseMarkdownTable, O as ParseError, S as parseScopeRef, T as parseCellValue, _ as findFieldById, a as resolveHarnessConfig, b as isFieldRef, d as MockAgent, f as createMockAgent, g as coerceToFieldPatch, h as coerceInputContext, i as runResearch, m as createHarness, n as isResearchForm, o as fillForm, p as FormHarness, r as validateResearchForm, t as VERSION, v as getFieldId, w as parseForm, x as isQualifiedRef, y as isCellRef } from "./src-Df0XX7UB.mjs";
+import { a as computeAllSummaries, c as computeStructureSummary, i as validate, l as isFormComplete, o as computeFormState, r as inspect, s as computeProgressSummary, t as applyPatches, u as serialize } from "./apply-DMQl-VVd.mjs";
+import { C as serializeScopeRef, D as parseRawTable, E as parseMarkdownTable, O as ParseError, S as parseScopeRef, T as parseCellValue, _ as findFieldById, a as resolveHarnessConfig, b as isFieldRef, d as MockAgent, f as createMockAgent, g as coerceToFieldPatch, h as coerceInputContext, i as runResearch, m as createHarness, n as isResearchForm, o as fillForm, p as FormHarness, r as validateResearchForm, t as VERSION, v as getFieldId, w as parseForm, x as isQualifiedRef, y as isCellRef } from "./src-o_5TSoHQ.mjs";
 import { n as serializeSession, t as parseSession } from "./session-uF0e6m6k.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, MarkformFrontmatterSchema, MockAgent, MultiCheckboxStateSchema, MultiSelectFieldSchema, MultiSelectValueSchema, NumberFieldSchema, NumberValueSchema, OptionIdSchema, OptionSchema, ParseError, PatchSchema, ProgressCountsSchema, ProgressStateSchema, ProgressSummarySchema, 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, YearFieldSchema, YearValueSchema, applyPatches, coerceInputContext, coerceToFieldPatch, computeAllSummaries, computeFormState, computeProgressSummary, computeStructureSummary, createHarness, createMockAgent, fillForm, findFieldById, getFieldId, inspect, isCellRef, isFieldRef, isFormComplete, isQualifiedRef, isResearchForm, parseCellValue, parseForm, parseMarkdownTable, parseRawTable, parseScopeRef, parseSession, resolveHarnessConfig, runResearch, serialize, serializeScopeRef, serializeSession, validate, validateResearchForm };

package/dist/{shared-BqPnYXrn.mjs → shared-DRlgu2ZJ.mjs}

@@ -1,6 +1,6 @@
 import YAML from "yaml";
-import { relative } from "node:path";
 import pc from "picocolors";
+import { relative } from "node:path";
 import { mkdir } from "node:fs/promises";
 import * as p from "@clack/prompts";
 

package/dist/{shared-CZsyShck.mjs → shared-u22MtBRo.mjs}

@@ -1,3 +1,3 @@
-import { a as formatPath, c as logError, d as logTiming, f as logVerbose, g as writeFile, h as shouldUseColors, i as formatOutput, l as logInfo, m as readFile, n as createSpinner, o as getCommandContext, p as logWarn, r as ensureFormsDir, s as logDryRun, t as OUTPUT_FORMATS, u as logSuccess } from "./shared-BqPnYXrn.mjs";
+import { a as formatPath, c as logError, d as logTiming, f as logVerbose, g as writeFile, h as shouldUseColors, i as formatOutput, l as logInfo, m as readFile, n as createSpinner, o as getCommandContext, p as logWarn, r as ensureFormsDir, s as logDryRun, t as OUTPUT_FORMATS, u as logSuccess } from "./shared-DRlgu2ZJ.mjs";
 
 export { writeFile };

package/dist/{src-Df0XX7UB.mjs → src-o_5TSoHQ.mjs}

@@ -1,6 +1,5 @@
 import { L as PatchSchema } from "./coreTypes-pyctKRgc.mjs";
-import { C as DEFAULT_ROLE_INSTRUCTIONS, P as getWebSearchConfig, S as DEFAULT_ROLES, _ as DEFAULT_MAX_TURNS, b as DEFAULT_RESEARCH_MAX_ISSUES_PER_TURN, g as DEFAULT_MAX_PATCHES_PER_TURN, h as DEFAULT_MAX_ISSUES_PER_TURN, n as getFieldsForRoles, p as AGENT_ROLE, r as inspect, t as applyPatches, u as serialize, x as DEFAULT_RESEARCH_MAX_PATCHES_PER_TURN, y as DEFAULT_PRIORITY } from "./apply-BCCiJzQr.mjs";
-import { createRequire } from "node:module";
+import { C as DEFAULT_ROLE_INSTRUCTIONS, N as getWebSearchConfig, S as DEFAULT_ROLES, _ as DEFAULT_MAX_TURNS, b as DEFAULT_RESEARCH_MAX_ISSUES_PER_TURN, g as DEFAULT_MAX_PATCHES_PER_TURN, h as DEFAULT_MAX_ISSUES_PER_TURN, n as getFieldsForRoles, p as AGENT_ROLE, r as inspect, t as applyPatches, u as serialize, x as DEFAULT_RESEARCH_MAX_PATCHES_PER_TURN, y as DEFAULT_PRIORITY } from "./apply-DMQl-VVd.mjs";
 import { z } from "zod";
 import Markdoc from "@markdoc/markdoc";
 import YAML from "yaml";
@@ -7613,6 +7612,7 @@ var LiveAgent = class {
 	enableWebSearch;
 	webSearchTools = null;
 	additionalTools;
+	callbacks;
 	constructor(config) {
 		this.model = config.model;
 		this.maxStepsPerTurn = config.maxStepsPerTurn ?? 3;
@@ -7621,6 +7621,7 @@ var LiveAgent = class {
 		this.provider = config.provider;
 		this.enableWebSearch = config.enableWebSearch;
 		this.additionalTools = config.additionalTools ?? {};
+		this.callbacks = config.callbacks;
 		if (this.enableWebSearch && this.provider) this.webSearchTools = loadWebSearchTools(this.provider);
 	}
 	/**
@@ -7646,14 +7647,18 @@ var LiveAgent = class {
 		if (this.systemPromptAddition) systemPrompt += "\n\n# Additional Context\n" + this.systemPromptAddition;
 		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 = {
+		const tools = wrapToolsWithCallbacks({
 			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,
 			...this.additionalTools
-		};
+		}, this.callbacks);
+		const modelId = this.model.modelId ?? "unknown";
+		if (this.callbacks?.onLlmCallStart) try {
+			this.callbacks.onLlmCallStart({ model: modelId });
+		} catch {}
 		const result = await generateText({
 			model: this.model,
 			system: systemPrompt,
@@ -7661,6 +7666,13 @@ var LiveAgent = class {
 			tools,
 			stopWhen: stepCountIs(this.maxStepsPerTurn)
 		});
+		if (this.callbacks?.onLlmCallEnd) try {
+			this.callbacks.onLlmCallEnd({
+				model: modelId,
+				inputTokens: result.usage?.inputTokens ?? 0,
+				outputTokens: result.usage?.outputTokens ?? 0
+			});
+		} catch {}
 		const patches = [];
 		const toolCallCounts = /* @__PURE__ */ new Map();
 		for (const step of result.steps) for (const toolCall of step.toolCalls) {
@@ -7797,6 +7809,60 @@ function findField(form, fieldId) {
 	return null;
 }
 /**
+* Wrap tools with callbacks for observability.
+*
+* Only wraps tools that have an execute function.
+* Declarative tools (schema only) are passed through unchanged.
+*/
+function wrapToolsWithCallbacks(tools, callbacks) {
+	if (!callbacks?.onToolStart && !callbacks?.onToolEnd) return tools;
+	const wrapped = {};
+	for (const [name$2, tool$1] of Object.entries(tools)) {
+		const execute = tool$1.execute;
+		if (typeof execute === "function") wrapped[name$2] = wrapTool(name$2, tool$1, execute, callbacks);
+		else wrapped[name$2] = tool$1;
+	}
+	return wrapped;
+}
+/**
+* Wrap a single tool with callbacks.
+*/
+function wrapTool(name$2, tool$1, originalExecute, callbacks) {
+	return {
+		...tool$1,
+		execute: async (input) => {
+			const startTime = Date.now();
+			if (callbacks.onToolStart) try {
+				callbacks.onToolStart({
+					name: name$2,
+					input
+				});
+			} catch {}
+			try {
+				const output = await originalExecute(input);
+				if (callbacks.onToolEnd) try {
+					callbacks.onToolEnd({
+						name: name$2,
+						output,
+						durationMs: Date.now() - startTime
+					});
+				} catch {}
+				return output;
+			} catch (error) {
+				if (callbacks.onToolEnd) try {
+					callbacks.onToolEnd({
+						name: name$2,
+						output: null,
+						durationMs: Date.now() - startTime,
+						error: error instanceof Error ? error.message : String(error)
+					});
+				} catch {}
+				throw error;
+			}
+		}
+	};
+}
+/**
 * Load web search tools for a provider.
 * Uses centralized config from llms.ts.
 */
@@ -7994,6 +8060,7 @@ function buildResult(form, turns, totalPatches, status, inputContextWarnings, re
 * const result = await fillForm({
 *   form: formMarkdown,
 *   model: 'anthropic/claude-sonnet-4-5',
+*   enableWebSearch: true,
 *   inputContext: {
 *     company_name: 'Apple Inc.',
 *   },
@@ -8001,8 +8068,10 @@ function buildResult(form, turns, totalPatches, status, inputContextWarnings, re
 *     ## Additional Context
 *     ${backgroundInfo}
 *   `,
-*   onTurnComplete: (progress) => {
-*     console.log(`Turn ${progress.turnNumber}: ${progress.requiredIssuesRemaining} remaining`);
+*   callbacks: {
+*     onTurnComplete: (progress) => {
+*       console.log(`Turn ${progress.turnNumber}: ${progress.requiredIssuesRemaining} remaining`);
+*     },
 *   },
 * });
 *
@@ -8079,7 +8148,8 @@ async function fillForm(options) {
 		targetRole: targetRoles[0] ?? AGENT_ROLE,
 		provider,
 		enableWebSearch: options.enableWebSearch,
-		additionalTools: options.additionalTools
+		additionalTools: options.additionalTools,
+		callbacks: options.callbacks
 	});
 	let turnCount = 0;
 	let stepResult = harness.step();
@@ -8088,6 +8158,12 @@ async function fillForm(options) {
 			ok: false,
 			reason: "cancelled"
 		}, inputContextWarnings, stepResult.issues);
+		if (options.callbacks?.onTurnStart) try {
+			options.callbacks.onTurnStart({
+				turnNumber: turnCount + 1,
+				issuesCount: stepResult.issues.length
+			});
+		} catch {}
 		const { patches, stats } = await agent.generatePatches(stepResult.issues, form, maxPatchesPerTurn);
 		if (options.signal?.aborted) return buildResult(form, turnCount, totalPatches, {
 			ok: false,
@@ -8102,9 +8178,9 @@ async function fillForm(options) {
 		stepResult = harness.apply(patches, stepResult.issues, llmStats);
 		totalPatches += patches.length;
 		turnCount++;
-		if (options.onTurnComplete) try {
+		if (options.callbacks?.onTurnComplete) try {
 			const requiredIssues = stepResult.issues.filter((i) => i.severity === "required");
-			options.onTurnComplete({
+			options.callbacks.onTurnComplete({
 				turnNumber: turnCount,
 				issuesShown: stepResult.issues.length,
 				patchesApplied: patches.length,
@@ -8266,15 +8342,8 @@ function validateResearchForm(form) {
 
 //#endregion
 //#region src/index.ts
-/**
-* Markform - Agent-friendly, human-readable, editable forms.
-*
-* This is the main library entry point that exports the core engine,
-* types, and utilities for working with .form.md files.
-*/
-const pkg = createRequire(import.meta.url)("../package.json");
-/** Markform version (read from package.json). */
-const VERSION = pkg.version;
+/** Markform version (injected at build time). */
+const VERSION = "0.1.6";
 
 //#endregion
 export { serializeScopeRef as C, parseRawTable as D, parseMarkdownTable as E, ParseError as O, parseScopeRef as S, parseCellValue as T, findFieldById as _, resolveHarnessConfig as a, isFieldRef as b, getProviderNames as c, MockAgent as d, createMockAgent as f, coerceToFieldPatch as g, coerceInputContext as h, runResearch as i, resolveModel as l, createHarness as m, isResearchForm as n, fillForm as o, FormHarness as p, validateResearchForm as r, getProviderInfo as s, VERSION as t, createLiveAgent as u, getFieldId as v, parseForm as w, isQualifiedRef as x, isCellRef as y };

package/docs/markform-apis.md

@@ -152,10 +152,57 @@ High-level API for filling a form with an AI model.
 const result = await fillForm({
   form: parsedForm,
   model: 'anthropic/claude-sonnet-4-5',
-  roles: ['agent'],
+  enableWebSearch: true,
+  targetRoles: ['agent'],
 });
 ```
 
+### FillCallbacks
+
+Optional callbacks for observing form-filling execution in real-time.
+All callbacks are optional and errors in callbacks don't abort filling.
+
+```typescript
+import type { FillCallbacks } from 'markform';
+
+const callbacks: FillCallbacks = {
+  onTurnStart: ({ turnNumber, issuesCount }) => {
+    console.log(`Turn ${turnNumber}: ${issuesCount} issues`);
+  },
+  onTurnComplete: (progress) => {
+    console.log(`Completed: ${progress.patchesApplied} patches applied`);
+  },
+  onToolStart: ({ name }) => {
+    spinner.message(`🔧 ${name}...`);
+  },
+  onToolEnd: ({ name, durationMs }) => {
+    console.log(`${name} completed in ${durationMs}ms`);
+  },
+  onLlmCallStart: ({ model }) => {
+    console.log(`Calling ${model}...`);
+  },
+  onLlmCallEnd: ({ inputTokens, outputTokens }) => {
+    console.log(`Tokens: ${inputTokens} in, ${outputTokens} out`);
+  },
+};
+
+await fillForm({
+  form: parsedForm,
+  model: 'anthropic/claude-sonnet-4-5',
+  enableWebSearch: true,
+  callbacks,
+});
+```
+
+| Callback | Parameters | Description |
+| --- | --- | --- |
+| `onTurnStart` | `{ turnNumber, issuesCount }` | Called when a turn begins |
+| `onTurnComplete` | `TurnProgress` | Called when a turn completes |
+| `onToolStart` | `{ name, input }` | Called before a tool executes |
+| `onToolEnd` | `{ name, output, durationMs, error? }` | Called after a tool completes |
+| `onLlmCallStart` | `{ model }` | Called before an LLM request |
+| `onLlmCallEnd` | `{ model, inputTokens, outputTokens }` | Called after an LLM response |
+
 ### createHarness(form, config?): FormHarness
 
 Create a harness for manual control over the fill loop.
@@ -187,6 +234,10 @@ import type {
   FieldValue,
   Patch,
   InspectResult,
+  FillCallbacks,
+  FillOptions,
+  FillResult,
+  TurnProgress,
   // ... many more
 } from 'markform';
 ```

package/docs/markform-spec.md

@@ -118,12 +118,20 @@ Built on [Markdoc’s tag syntax specification][markdoc-spec] and
 ---
 markform:
   spec: MF/0.1
+  run_mode: research       # optional: interactive | fill | research
   form_summary: { ... }    # derived: structure summary
   form_progress: { ... }   # derived: progress summary
   form_state: complete|incomplete|invalid|empty   # derived: overall progress state
 ---
 ```
 
+**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.
+
 **Behavioral rules (*required*):**
 
 - *required:* `form_summary`, `form_progress`, and `form_state` are derived,
@@ -1343,6 +1351,7 @@ interface FormMetadata {
   markformVersion: string;
   roles: string[];                        // available roles for field assignment
   roleInstructions: Record<string, string>; // instructions per role
+  runMode?: 'interactive' | 'fill' | 'research';  // optional: hint for CLI tools
 }
 
 // ParsedForm: canonical internal representation returned by parseForm()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "markform",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Markdown forms for token-friendly workflows",
   "license": "AGPL-3.0-or-later",
   "author": "Joshua Levy",