markform 0.1.23 → 0.1.25

package/docs/markform-apis.md

@@ -138,6 +138,12 @@ Each patch has an `op` and `fieldId`.
 | `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"}] }` |
+| `append_table` | table | `{ "op": "append_table", "fieldId": "data", "value": [{"col1": "v2"}] }` |
+| `delete_table` | table | `{ "op": "delete_table", "fieldId": "data", "value": [0, 2] }` |
+| `append_string_list` | string_list | `{ "op": "append_string_list", "fieldId": "tags", "value": ["c"] }` |
+| `delete_string_list` | string_list | `{ "op": "delete_string_list", "fieldId": "tags", "value": ["a"] }` |
+| `append_url_list` | url_list | `{ "op": "append_url_list", "fieldId": "sources", "value": ["https://new"] }` |
+| `delete_url_list` | url_list | `{ "op": "delete_url_list", "fieldId": "sources", "value": ["https://old"] }` |
 | `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" }` |
@@ -233,8 +239,8 @@ const result = await fillForm({
 **Behavior:**
 - `enableParallel: false` (default): All fields filled serially, `parallel` attributes
   ignored. The `order` attribute still controls issue filtering.
-- `enableParallel: true`: Batch items run concurrently (up to `maxParallelAgents`).
-  Each agent runs a multi-turn loop with rejection feedback, same as the serial path.
+- `enableParallel: true`: Batch items run concurrently (up to `maxParallelAgents`). Each
+  agent runs a multi-turn loop with rejection feedback, same as the serial path.
 - If the form has no `parallel` batches, falls back to serial automatically.
 - `FillResult` shape is identical regardless of serial or parallel execution.
 
@@ -250,6 +256,16 @@ The `status` field in `FillResult` indicates success or failure:
 | `{ ok: false, reason: 'cancelled' }` | Aborted via signal |
 | `{ ok: false, reason: 'error' }` | Unexpected error |
 
+When `ok` is `false`, the status also includes:
+
+- `message?: string` — Human-readable error description
+- `error?: Error` — The original Error object with its full cause chain preserved (when
+  the caught value was an Error instance).
+  For `MarkformLlmError` instances, this carries `.statusCode`, `.responseBody`,
+  `.provider`, `.model`, and `.retryable` properties.
+  Not serialized into FillRecord — use for in-memory diagnostics and real-time error
+  handling.
+
 ### Resumable Form Fills
 
 For orchestrated environments with timeout constraints (e.g., Convex, AWS Step
@@ -345,6 +361,7 @@ await fillForm({
 | `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 |
+| `onError` | `(error: Error, { turnNumber })` | Called when an error occurs during the fill loop |
 
 **TurnProgress fields:**
 
@@ -370,8 +387,9 @@ 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.
+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({
@@ -497,10 +515,10 @@ interface HeadingInfo {
 
 ### findEnclosingHeadings(markdown: string, line: number): HeadingInfo[]
 
-Find all headings that enclose a given line position. Returns headings from innermost
-(most specific) to outermost (least specific).
+Find all headings that enclose a given line position.
+Returns headings from innermost (most specific) to outermost (least specific).
 
-A heading "encloses" a line if the heading appears before the line and no heading of
+A heading “encloses” a line if the heading appears before the line and no heading of
 equal or higher level appears between them.
 
 ### findAllCheckboxes(markdown: string): CheckboxInfo[]