markform 0.1.18 → 0.1.20

package/docs/markform-apis.md

@@ -207,6 +207,7 @@ const result = await fillForm({
 | `callbacks` | `FillCallbacks` | `undefined` | Progress callbacks |
 | `signal` | `AbortSignal` | `undefined` | Cancellation signal |
 | `additionalTools` | `Record<string, Tool>` | `undefined` | Custom tools for agent |
+| `recordFill` | `boolean` | (required) | Collect detailed FillRecord with timeline and stats |
 
 ### Parallel Execution
 
@@ -343,6 +344,7 @@ await fillForm({
 | `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 |
+| `onWebSearch` | `{ query, resultCount, provider }` | Called when a web search is performed |
 
 **TurnProgress fields:**
 
@@ -366,6 +368,85 @@ interface PatchRejection {
 }
 ```
 
+### FillRecord
+
+When `recordFill: true`, the `FillResult.record` contains a complete record of everything
+that happened during the fill operation. Useful for cost analysis, debugging, and auditing.
+
+```typescript
+const result = await fillForm({
+  form: formMarkdown,
+  model: 'anthropic/claude-sonnet-4-5',
+  enableWebSearch: true,
+  captureWireFormat: false,
+  recordFill: true,
+});
+
+if (result.record) {
+  console.log(`Session: ${result.record.sessionId}`);
+  console.log(`Duration: ${result.record.durationMs}ms`);
+  console.log(`Tokens: ${result.record.llm.inputTokens} in, ${result.record.llm.outputTokens} out`);
+  console.log(`Tool calls: ${result.record.toolSummary.totalCalls}`);
+}
+```
+
+**FillRecord fields:**
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `sessionId` | `string` | Unique session identifier (UUID) |
+| `startedAt` | `string` | ISO datetime when fill started |
+| `completedAt` | `string` | ISO datetime when fill completed |
+| `durationMs` | `number` | Total duration in milliseconds |
+| `form` | `object` | Form metadata (id, title, structure) |
+| `status` | `string` | `'completed'`, `'partial'`, `'failed'`, `'cancelled'` |
+| `formProgress` | `ProgressCounts` | Final form progress counts |
+| `llm` | `object` | LLM usage (provider, model, tokens) |
+| `toolSummary` | `ToolSummary` | Aggregated tool statistics |
+| `timingBreakdown` | `TimingBreakdown` | Time spent in LLM, tools, overhead |
+| `timeline` | `TimelineEntry[]` | Turn-by-turn execution history |
+| `execution` | `ExecutionMetadata` | Parallel execution details |
+| `customData` | `object` | Optional client-defined data |
+
+### formatFillRecordSummary(record, options?): string
+
+Format a FillRecord as a human-readable text summary.
+
+```typescript
+import { formatFillRecordSummary } from 'markform';
+
+const summary = formatFillRecordSummary(result.record, { verbose: true });
+console.log(summary);
+```
+
+**Output example:**
+
+```
+Fill completed in 12.4s (5 turns)
+
+Tokens:  2,450 input / 890 output (anthropic/claude-sonnet-4-5)
+Tools:   12 calls (11 succeeded, 1 failed)
+         - web_search: 5 calls, avg 1.2s, p95 2.1s
+         - fill_form: 7 calls, avg 45ms
+
+Timing:  55% LLM (6.8s) | 41% tools (5.1s) | 4% overhead (0.5s)
+
+Progress: 18/20 fields filled (90%)
+```
+
+**CLI usage:**
+
+The CLI provides `--record-fill` to write a sidecar `.fill.json` file:
+
+```bash
+markform fill input.form.md -o output.form.md --record-fill
+# Creates: output.form.md (filled form)
+#          output.fill.json (FillRecord JSON)
+```
+
+The CLI always prints a summary to stderr (use `--quiet` to suppress, `--verbose` for
+more detail).
+
 ### createHarness(form, config?): FormHarness
 
 Create a harness for manual control over the fill loop.

package/docs/markform-reference.md

@@ -61,7 +61,21 @@ markform:
 
 ## Conventions
 
-Use `.form.md` for Markform files.
+### File Extensions
+
+| File Type | Extension | Description |
+|-----------|-----------|-------------|
+| Form | `.form.md` | Markform source and filled forms |
+| Fill Record | `.fill.json` | Execution metadata (sidecar file) |
+| Report | `.report.md` | Filtered human-readable output |
+| Schema | `.schema.json` | JSON Schema for form structure |
+| Values | `.yml` or `.json` | Exported field values |
+
+**Recommended:** Use `.form.md` for all Markform files. This enables:
+- Auto-discovery of fill records by `markform serve`
+- Consistent tooling behavior across CLI commands
+- Clear distinction from regular markdown files
+
 Markform uses HTML comment syntax for structure tags, which render invisibly on GitHub.
 
 ### Syntax

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "markform",
-  "version": "0.1.18",
+  "version": "0.1.20",
   "description": "Markdown forms for token-friendly workflows",
   "license": "AGPL-3.0-or-later",
   "author": "Joshua Levy",
@@ -55,35 +55,37 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@ai-sdk/deepseek": "^2.0.1",
-    "@ai-sdk/google": "^3.0.1",
-    "@ai-sdk/openai": "^3.0.1",
-    "@ai-sdk/xai": "^3.0.2",
-    "@clack/prompts": "^0.11.0",
+    "@ai-sdk/deepseek": "^2.0.16",
+    "@ai-sdk/google": "^3.0.19",
+    "@ai-sdk/openai": "^3.0.24",
+    "@ai-sdk/xai": "^3.0.45",
+    "@clack/prompts": "^1.0.0",
     "@markdoc/markdoc": "^0.5.4",
-    "ai": "^6.0.3",
+    "ai": "^6.0.66",
     "atomically": "^2.1.0",
-    "commander": "^14.0.2",
+    "commander": "^14.0.3",
     "dotenv": "^17.2.3",
     "jiti": "^2.6.1",
     "js-sha256": "^0.11.1",
     "picocolors": "^1.1.1",
+    "ulid": "^3.0.2",
+    "undici": "^7.19.2",
     "yaml": "^2.8.2",
-    "zod": "^4.2.1"
+    "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@ai-sdk/anthropic": "^3.0.1",
-    "@types/node": "^22.15.30",
-    "@vitest/coverage-v8": "^4.0.16",
+    "@ai-sdk/anthropic": "^3.0.34",
+    "@types/node": "^25.1.0",
+    "@vitest/coverage-v8": "^4.0.18",
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
     "c8": "^10.1.3",
     "monocart-coverage-reports": "^2.12.9",
-    "publint": "^0.3.16",
+    "publint": "^0.3.17",
     "tryscript": "^0.1.6",
-    "tsdown": "^0.18.3",
+    "tsdown": "^0.20.1",
     "typescript": "^5.9.3",
-    "vitest": "^4.0.16"
+    "vitest": "^4.0.18"
   },
   "scripts": {
     "copy-docs": "cp ../../README.md . && mkdir -p docs && cp ../../docs/markform-spec.md docs/ && cp ../../docs/markform-reference.md docs/ && cp ../../docs/markform-apis.md docs/",