markform 0.1.0 → 0.1.2

package/dist/index.d.mts

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
 
-import { $ as MultiSelectFieldSchema, $t as StringFieldSchema, A as FieldValue, At as SetNumberPatch, B as InspectIssue, Bt as SimpleCheckboxState, C as FieldGroup, Ct as SessionTranscriptSchema, D as FieldProgress, Dt as SetCheckboxesPatchSchema, E as FieldKindSchema, Et as SetCheckboxesPatch, F as HarnessConfig, Ft as SetStringListPatchSchema, G as IssueReasonSchema, Gt as SingleSelectValueSchema, H as InspectResult, Ht as SingleSelectField, I as HarnessConfigSchema, It as SetStringPatch, J as MarkformFrontmatter, Jt as SourceRange, K as IssueScope, Kt as SourcePosition, L as Id, Lt as SetStringPatchSchema, M as FillMode, Mt as SetSingleSelectPatch, N as FormSchema, Nt as SetSingleSelectPatchSchema, O as FieldProgressSchema, Ot as SetMultiSelectPatch, P as FormSchemaSchema, Pt as SetStringListPatch, Q as MultiSelectField, Qt as StringField, R as IdIndexEntry, Rt as Severity, S as FieldBase, St as SessionTranscript, T as FieldKind, Tt as SessionTurnSchema, U as InspectResultSchema, Ut as SingleSelectFieldSchema, V as InspectIssueSchema, Vt as SimpleCheckboxStateSchema, W as IssueReason, Wt as SingleSelectValue, X as MultiCheckboxState, Xt as StepResult, Y as MarkformFrontmatterSchema, Yt as SourceRangeSchema, Z as MultiCheckboxStateSchema, Zt as StepResultSchema, _ as DocumentationTag, _t as ProgressSummary, a as CheckboxProgressCounts, an as StringValueSchema, at as NumberValueSchema, b as ExplicitCheckboxValueSchema, bt as SessionFinal, c as CheckboxValueSchema, cn as ValidationIssue, ct as OptionIdSchema, d as CheckboxesValue, dn as ValidatorFn, dt as Patch, en as StringListField, et as MultiSelectValue, f as CheckboxesValueSchema, fn as ValidatorRef, ft as PatchSchema, g as DocumentationBlockSchema, gt as ProgressStateSchema, h as DocumentationBlock, ht as ProgressState, i as CheckboxModeSchema, in as StringValue, it as NumberValue, j as FieldValueSchema, jt as SetNumberPatchSchema, k as FieldSchema, kt as SetMultiSelectPatchSchema, l as CheckboxesField, ln as ValidationIssueSchema, lt as OptionSchema, m as ClearFieldPatchSchema, mn as ValidatorRegistry, mt as ProgressCountsSchema, n as ApplyResultSchema, nn as StringListValue, nt as NumberField, o as CheckboxProgressCountsSchema, on as StructureSummary, ot as Option, p as ClearFieldPatch, pn as ValidatorRefSchema, pt as ProgressCounts, q as IssueScopeSchema, qt as SourcePositionSchema, r as CheckboxMode, rn as StringListValueSchema, rt as NumberFieldSchema, s as CheckboxValue, sn as StructureSummarySchema, st as OptionId, t as ApplyResult, tn as StringListFieldSchema, tt as MultiSelectValueSchema, u as CheckboxesFieldSchema, un as ValidatorContext, ut as ParsedForm, v as DocumentationTagSchema, vt as ProgressSummarySchema, w as FieldGroupSchema, wt as SessionTurn, x as Field, xt as SessionFinalSchema, y as ExplicitCheckboxValue, yt as QualifiedOptionRef, z as IdSchema, zt as SeveritySchema } from "./coreTypes-T7dAuewt.mjs";
+import { $ as MarkformFrontmatter, $t as SingleSelectValueSchema, A as FieldProgressSchema, At as SessionTranscriptSchema, B as HarnessConfig, Bt as SetSingleSelectPatch, C as Field, Ct as ProgressStateSchema, D as FieldKind, Dt as SessionFinal, E as FieldGroupSchema, Et as QualifiedOptionRef, F as FieldValueSchema, Ft as SetCheckboxesPatchSchema, G as InspectIssue, Gt as SetStringPatchSchema, H as Id, Ht as SetStringListPatch, I as FillMode, It as SetMultiSelectPatch, J as InspectResultSchema, Jt as SimpleCheckboxState, K as InspectIssueSchema, Kt as Severity, L as FormSchema, Lt as SetMultiSelectPatchSchema, M as FieldResponseSchema, Mt as SessionTurnSchema, N as FieldSchema, Nt as SessionTurnStats, O as FieldKindSchema, Ot as SessionFinalSchema, P as FieldValue, Pt as SetCheckboxesPatch, Q as IssueScopeSchema, Qt as SingleSelectValue, R as FormSchemaSchema, Rt as SetNumberPatch, S as ExplicitCheckboxValueSchema, Sn as ValidatorRegistry, St as ProgressState, T as FieldGroup, Tt as ProgressSummarySchema, U as IdIndexEntry, Ut as SetStringListPatchSchema, V as HarnessConfigSchema, Vt as SetSingleSelectPatchSchema, W as IdSchema, Wt as SetStringPatch, X as IssueReasonSchema, Xt as SingleSelectField, Y as IssueReason, Yt as SimpleCheckboxStateSchema, Z as IssueScope, Zt as SingleSelectFieldSchema, _ as DocumentationBlock, _n as ValidationIssueSchema, _t as ParsedForm, a as CheckboxMode, an as StepResultSchema, at as MultiSelectValue, b as DocumentationTagSchema, bn as ValidatorRef, bt as ProgressCounts, c as CheckboxProgressCountsSchema, cn as StringListField, ct as Note, d as CheckboxesField, dn as StringListValueSchema, dt as NumberValue, en as SourcePosition, et as MarkformFrontmatterSchema, f as CheckboxesFieldSchema, fn as StringValue, ft as NumberValueSchema, g as ClearFieldPatchSchema, gn as ValidationIssue, gt as OptionSchema, h as ClearFieldPatch, hn as StructureSummarySchema, ht as OptionIdSchema, i as ApplyResultSchema, in as StepResult, it as MultiSelectFieldSchema, j as FieldResponse, jt as SessionTurn, k as FieldProgress, kt as SessionTranscript, l as CheckboxValue, ln as StringListFieldSchema, lt as NumberField, m as CheckboxesValueSchema, mn as StructureSummary, mt as OptionId, n as AnswerStateSchema, nn as SourceRange, nt as MultiCheckboxStateSchema, o as CheckboxModeSchema, on as StringField, ot as MultiSelectValueSchema, p as CheckboxesValue, pn as StringValueSchema, pt as Option, q as InspectResult, qt as SeveritySchema, r as ApplyResult, rn as SourceRangeSchema, rt as MultiSelectField, s as CheckboxProgressCounts, sn as StringFieldSchema, st as NodeType, t as AnswerState, tn as SourcePositionSchema, tt as MultiCheckboxState, u as CheckboxValueSchema, un as StringListValue, ut as NumberFieldSchema, v as DocumentationBlockSchema, vn as ValidatorContext, vt as Patch, w as FieldBase, wt as ProgressSummary, x as ExplicitCheckboxValue, xn as ValidatorRefSchema, xt as ProgressCountsSchema, y as DocumentationTag, yn as ValidatorFn, yt as PatchSchema, z as FrontmatterHarnessConfig, zt as SetNumberPatchSchema } from "./coreTypes-BXhhz9Iq.mjs";
+import "@markdoc/markdoc";
 import { LanguageModel } from "ai";
 
-//#region src/engine/parse.d.ts
+//#region src/engine/parseHelpers.d.ts
 
 /** Parse error with source location info */
 declare class ParseError extends Error {
@@ -11,6 +12,8 @@ declare class ParseError extends Error {
   readonly col?: number | undefined;
   constructor(message: string, line?: number | undefined, col?: number | undefined);
 }
+//#endregion
+//#region src/engine/parse.d.ts
 /**
  * Parse a Markform .form.md document.
  *
@@ -21,9 +24,10 @@ declare class ParseError extends Error {
 declare function parseForm(markdown: string): ParsedForm;
 //#endregion
 //#region src/engine/serialize.d.ts
+
 interface SerializeOptions {
-  /** Markform version to use in frontmatter. Defaults to "0.1.0". */
-  markformVersion?: string;
+  /** Markform spec version to use in frontmatter. Defaults to MF_SPEC_VERSION. */
+  specVersion?: string;
 }
 /**
  * Serialize a ParsedForm to canonical Markdoc markdown format.
@@ -46,11 +50,12 @@ declare function computeStructureSummary(schema: FormSchema): StructureSummary;
  * Compute a progress summary for a form.
  *
  * @param schema - The form schema
- * @param values - Current field values
+ * @param responsesByFieldId - Current field responses (state + optional value)
+ * @param notes - Notes attached to fields/groups/form
  * @param issues - Validation issues (from inspect)
  * @returns Progress summary with field states and counts
  */
-declare function computeProgressSummary(schema: FormSchema, values: Record<Id, FieldValue>, issues: InspectIssue[]): ProgressSummary;
+declare function computeProgressSummary(schema: FormSchema, responsesByFieldId: Record<Id, FieldResponse>, notes: Note[], issues: InspectIssue[]): ProgressSummary;
 /**
  * Compute the overall form state from progress summary.
  *
@@ -61,6 +66,16 @@ declare function computeFormState(progress: ProgressSummary): ProgressState;
 /**
  * Determine if the form is complete (ready for submission).
  *
+ * A form is complete when:
+ * 1. No aborted fields (aborted fields block completion)
+ * 2. No required fields are empty
+ * 3. No fields have validation errors
+ * 4. No fields are in incomplete state (e.g., partial checkbox completion)
+ * 5. All fields must be addressed (answered + skipped == total)
+ *
+ * Every field must be explicitly addressed - either filled with a value or
+ * skipped with a reason. This ensures agents fully process all fields.
+ *
  * @param progress - The progress summary
  * @returns True if the form is complete
  */
@@ -75,11 +90,12 @@ interface ComputedSummaries {
  * Compute all summaries for a parsed form.
  *
  * @param schema - The form schema
- * @param values - Current field values
+ * @param responsesByFieldId - Current field responses (state + optional value)
+ * @param notes - Notes attached to fields/groups/form
  * @param issues - Validation issues
  * @returns All computed summaries
  */
-declare function computeAllSummaries(schema: FormSchema, values: Record<Id, FieldValue>, issues: InspectIssue[]): ComputedSummaries;
+declare function computeAllSummaries(schema: FormSchema, responsesByFieldId: Record<Id, FieldResponse>, notes: Note[], issues: InspectIssue[]): ComputedSummaries;
 //#endregion
 //#region src/engine/validate.d.ts
 interface ValidateOptions {
@@ -205,7 +221,7 @@ declare function coerceToFieldPatch(form: ParsedForm, fieldId: string, rawValue:
 declare function coerceInputContext(form: ParsedForm, inputContext: InputContext): CoerceInputContextResult;
 //#endregion
 //#region src/harness/harness.d.ts
-type HarnessState = "init" | "step" | "wait" | "complete";
+type HarnessState = 'init' | 'step' | 'wait' | 'complete';
 /**
  * Form harness for managing agent-driven form filling.
  */
@@ -234,6 +250,13 @@ declare class FormHarness {
   getForm(): ParsedForm;
   /**
    * Check if the harness has reached max turns.
+   *
+   * Returns true when we've completed all allowed turns. This happens when:
+   * - turnNumber >= maxTurns AND we've already applied (state is "complete")
+   * - OR turnNumber > maxTurns (we've exceeded the limit)
+   *
+   * This allows the harness loop to run N times when maxTurns=N by returning
+   * false when we're at turn N but haven't applied yet (state is "wait").
    */
   hasReachedMaxTurns(): boolean;
   /**
@@ -254,9 +277,19 @@ declare class FormHarness {
    *
    * @param patches - Patches to apply
    * @param issues - Issues that were shown to the agent (for recording)
+   * @param llmStats - Optional LLM stats for session logging
    * @returns StepResult after applying patches
    */
-  apply(patches: Patch[], issues: InspectIssue[]): StepResult;
+  apply(patches: Patch[], issues: InspectIssue[], llmStats?: SessionTurnStats): StepResult;
+  /**
+   * Compute step result from inspect result.
+   * Applies issue filtering and computes step budget.
+   */
+  private computeStepResult;
+  /**
+   * Record a turn in the session transcript.
+   */
+  private recordTurn;
   /**
    * Check if the form is complete.
    */
@@ -303,6 +336,51 @@ declare class FormHarness {
 declare function createHarness(form: ParsedForm, config?: Partial<HarnessConfig>): FormHarness;
 //#endregion
 //#region src/harness/harnessTypes.d.ts
+/**
+ * Per-turn statistics from LLM calls.
+ *
+ * Tracks token usage, tool calls, and form progress for observability.
+ */
+interface TurnStats {
+  /** Input tokens for this turn (from provider usage) */
+  inputTokens?: number;
+  /** Output tokens for this turn (from provider usage) */
+  outputTokens?: number;
+  /** Tool calls made during this turn */
+  toolCalls: {
+    /** Tool name */
+    name: string;
+    /** Number of times called */
+    count: number;
+  }[];
+  /** Form progress after this turn */
+  formProgress: {
+    /** Fields with values */
+    answeredFields: number;
+    /** Fields marked as skipped */
+    skippedFields: number;
+    /** Required issues still remaining */
+    requiredRemaining: number;
+    /** Optional/recommended issues still remaining */
+    optionalRemaining: number;
+  };
+  /** Full prompts sent to LLM (for verbose logging) */
+  prompts?: {
+    /** System prompt with instructions */
+    system: string;
+    /** Context prompt with form state and issues */
+    context: string;
+  };
+}
+/**
+ * Response from agent's generatePatches call.
+ */
+interface AgentResponse {
+  /** Patches to apply */
+  patches: Patch[];
+  /** Per-turn stats (undefined for MockAgent) */
+  stats?: TurnStats;
+}
 /**
  * Interface for agents that can generate patches.
  */
@@ -313,9 +391,9 @@ interface Agent {
    * @param issues - Prioritized issues from harness step
    * @param form - Current form state
    * @param maxPatches - Maximum number of patches to generate
-   * @returns Promise resolving to array of patches to apply
+   * @returns Promise resolving to patches and optional stats
    */
-  generatePatches(issues: InspectIssue[], form: ParsedForm, maxPatches: number): Promise<Patch[]>;
+  generatePatches(issues: InspectIssue[], form: ParsedForm, maxPatches: number): Promise<AgentResponse>;
 }
 /**
  * Options for the fillForm function.
@@ -337,7 +415,7 @@ interface FillOptions {
   /** Maximum patches per turn (default: 20) */
   maxPatchesPerTurn?: number;
   /** Maximum issues to show per turn (default: 10) */
-  maxIssues?: number;
+  maxIssuesPerTurn?: number;
   /** Target roles to fill (default: ['agent']) */
   targetRoles?: string[];
   /** Fill mode: 'continue' (skip filled) or 'overwrite' (re-fill) */
@@ -361,6 +439,8 @@ interface TurnProgress {
   patchesApplied: number;
   requiredIssuesRemaining: number;
   isComplete: boolean;
+  /** Per-turn stats from LLM (undefined for MockAgent) */
+  stats?: TurnStats;
 }
 /**
  * Fill status indicating success or failure reason.
@@ -369,7 +449,7 @@ type FillStatus = {
   ok: true;
 } | {
   ok: false;
-  reason: "max_turns" | "cancelled" | "error";
+  reason: 'max_turns' | 'cancelled' | 'error';
   message?: string;
 };
 /**
@@ -394,7 +474,7 @@ interface FillResult {
   remainingIssues?: {
     ref: string;
     message: string;
-    severity: "required" | "recommended";
+    severity: 'required' | 'recommended';
     priority: number;
   }[];
 }
@@ -416,9 +496,15 @@ declare class MockAgent implements Agent {
    * Generate patches from the completed mock to address issues.
    *
    * Processes issues in priority order, generating patches for
-   * fields that have values in the completed mock.
+   * fields that have values in the completed mock. For fields with no
+   * value (empty optional fields), generates skip_field patches.
+   * Returns AgentResponse with patches but no stats (mock doesn't track LLM usage).
    */
-  generatePatches(issues: InspectIssue[], _form: ParsedForm, maxPatches: number): Promise<Patch[]>;
+  generatePatches(issues: InspectIssue[], _form: ParsedForm, maxPatches: number): Promise<AgentResponse>;
+  /**
+   * Check if a field value actually has content (not null/empty).
+   */
+  private hasValue;
   /**
    * Create a patch for a field based on its kind and completed value.
    */
@@ -469,6 +555,98 @@ declare function createMockAgent(completedForm: ParsedForm): MockAgent;
  */
 declare function fillForm(options: FillOptions): Promise<FillResult>;
 //#endregion
+//#region src/harness/harnessConfigResolver.d.ts
+/**
+ * Resolve harness configuration by merging options from multiple sources.
+ *
+ * Precedence (highest to lowest):
+ * 1. options parameter (API-provided)
+ * 2. form.metadata.harnessConfig (from frontmatter)
+ * 3. Default constants
+ *
+ * @param form The parsed form (may contain frontmatter harness config)
+ * @param options API-provided options to override defaults
+ * @returns Resolved harness configuration
+ */
+declare function resolveHarnessConfig(form: ParsedForm, options?: Partial<FillOptions>): HarnessConfig;
+//#endregion
+//#region src/research/researchTypes.d.ts
+/**
+ * Research execution status.
+ */
+type ResearchStatus = 'completed' | 'incomplete' | 'max_turns_reached';
+/**
+ * Result of a research fill operation.
+ */
+interface ResearchResult {
+  /** Final status of the research */
+  status: ResearchStatus;
+  /** The filled form */
+  form: ParsedForm;
+  /** Optional session transcript for debugging */
+  transcript?: SessionTranscript;
+  /** Total harness turns executed */
+  totalTurns: number;
+  /** Total input tokens used (if available) */
+  inputTokens?: number;
+  /** Total output tokens used (if available) */
+  outputTokens?: number;
+  /** Tools available to the agent */
+  availableTools?: string[];
+  /** Path to saved .form.md file */
+  formPath?: string;
+  /** Path to saved .raw.md file */
+  rawPath?: string;
+  /** Path to saved .yaml file */
+  yamlPath?: string;
+}
+//#endregion
+//#region src/research/runResearch.d.ts
+/**
+ * Options for runResearch (FillOptions without form, since form is a separate parameter).
+ */
+type ResearchOptions = Omit<FillOptions, 'form'>;
+/**
+ * Run research fill on a form.
+ *
+ * This function fills a form using an LLM with optional web search capabilities.
+ * It resolves configuration from multiple sources (options > frontmatter > defaults)
+ * and executes the harness loop until completion or max turns.
+ *
+ * @param form The parsed form to fill
+ * @param options Fill options including model specification
+ * @returns Research result with filled form and statistics
+ */
+declare function runResearch(form: ParsedForm, options: ResearchOptions): Promise<ResearchResult>;
+//#endregion
+//#region src/research/researchFormValidation.d.ts
+/**
+ * Check if a form is configured for research mode.
+ *
+ * A form is considered a research form if it has web search configuration
+ * in its frontmatter metadata, indicated by:
+ * - webSearchModel: model ID for web search capability
+ * - enableWebSearch: boolean flag to enable web search
+ *
+ * @param form The parsed form to check
+ * @returns true if the form is configured for research
+ */
+declare function isResearchForm(form: ParsedForm): boolean;
+/**
+ * Validate that a form is suitable for research fill.
+ *
+ * Research forms should:
+ * 1. Have agent-role fields to fill
+ * 2. Not be already complete
+ *
+ * @param form The parsed form to validate
+ * @returns Object with isValid and optional error message
+ */
+declare function validateResearchForm(form: ParsedForm): {
+  isValid: boolean;
+  error?: string;
+};
+//#endregion
 //#region src/index.d.ts
 /**
  * Markform - Agent-friendly, human-readable, editable forms.
@@ -479,4 +657,4 @@ declare function fillForm(options: FillOptions): Promise<FillResult>;
 /** Markform version. */
 declare const VERSION = "0.1.0";
 //#endregion
-export { type ApplyResult, ApplyResultSchema, type CheckboxMode, CheckboxModeSchema, type CheckboxProgressCounts, CheckboxProgressCountsSchema, type CheckboxValue, CheckboxValueSchema, type CheckboxesField, CheckboxesFieldSchema, type CheckboxesValue, CheckboxesValueSchema, type ClearFieldPatch, ClearFieldPatchSchema, type CoerceInputContextResult, type CoercionResult, type ComputedSummaries, type DocumentationBlock, DocumentationBlockSchema, type DocumentationTag, DocumentationTagSchema, type ExplicitCheckboxValue, ExplicitCheckboxValueSchema, type Field, type FieldBase, type FieldGroup, FieldGroupSchema, type FieldKind, FieldKindSchema, type FieldProgress, FieldProgressSchema, FieldSchema, type FieldValue, FieldValueSchema, type FillOptions, type FillResult, type FillStatus, FormHarness, type FormSchema, FormSchemaSchema, 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 NumberField, NumberFieldSchema, type NumberValue, NumberValueSchema, type Option, type OptionId, OptionIdSchema, OptionSchema, ParseError, type ParsedForm, type Patch, PatchSchema, type ProgressCounts, ProgressCountsSchema, type ProgressState, ProgressStateSchema, type ProgressSummary, ProgressSummarySchema, type QualifiedOptionRef, type RawFieldValue, type SerializeOptions, type SessionFinal, SessionFinalSchema, type SessionTranscript, SessionTranscriptSchema, type SessionTurn, SessionTurnSchema, type SetCheckboxesPatch, SetCheckboxesPatchSchema, type SetMultiSelectPatch, SetMultiSelectPatchSchema, type SetNumberPatch, SetNumberPatchSchema, type SetSingleSelectPatch, SetSingleSelectPatchSchema, type SetStringListPatch, SetStringListPatchSchema, type SetStringPatch, SetStringPatchSchema, 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 TurnProgress, VERSION, type ValidateOptions, type ValidateResult, type ValidationIssue, ValidationIssueSchema, type ValidatorContext, type ValidatorFn, type ValidatorRef, ValidatorRefSchema, type ValidatorRegistry, applyPatches, coerceInputContext, coerceToFieldPatch, computeAllSummaries, computeFormState, computeProgressSummary, computeStructureSummary, createHarness, createMockAgent, fillForm, findFieldById, inspect, isFormComplete, parseForm, parseSession, serialize, serializeSession, validate };
+export { type AgentResponse, type AnswerState, AnswerStateSchema, type ApplyResult, ApplyResultSchema, type CheckboxMode, CheckboxModeSchema, type CheckboxProgressCounts, CheckboxProgressCountsSchema, type CheckboxValue, CheckboxValueSchema, type CheckboxesField, CheckboxesFieldSchema, type CheckboxesValue, CheckboxesValueSchema, type ClearFieldPatch, ClearFieldPatchSchema, type CoerceInputContextResult, type CoercionResult, type ComputedSummaries, 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 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 ParsedForm, type Patch, PatchSchema, type ProgressCounts, ProgressCountsSchema, type ProgressState, ProgressStateSchema, type ProgressSummary, ProgressSummarySchema, type QualifiedOptionRef, 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 SetMultiSelectPatch, SetMultiSelectPatchSchema, type SetNumberPatch, SetNumberPatchSchema, type SetSingleSelectPatch, SetSingleSelectPatchSchema, type SetStringListPatch, SetStringListPatchSchema, type SetStringPatch, SetStringPatchSchema, 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 TurnProgress, type TurnStats, VERSION, type ValidateOptions, type ValidateResult, type ValidationIssue, ValidationIssueSchema, type ValidatorContext, type ValidatorFn, type ValidatorRef, ValidatorRefSchema, type ValidatorRegistry, applyPatches, coerceInputContext, coerceToFieldPatch, computeAllSummaries, computeFormState, computeProgressSummary, computeStructureSummary, createHarness, createMockAgent, fillForm, findFieldById, inspect, isFormComplete, isResearchForm, parseForm, parseSession, resolveHarnessConfig, runResearch, serialize, serializeSession, validate, validateResearchForm };

package/dist/index.mjs

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

package/dist/session-Bqnwi9wp.mjs

@@ -0,0 +1,110 @@
+import { R as SessionTranscriptSchema } from "./coreTypes-Dful87E0.mjs";
+import YAML from "yaml";
+
+//#region src/engine/session.ts
+/**
+* Session module - parsing and serializing session transcripts.
+*
+* Session transcripts are used for golden testing and session replay.
+* They capture the full interaction between the harness and agent.
+*/
+/**
+* Parse a session transcript from YAML string.
+*
+* Converts snake_case keys to camelCase for TypeScript consumption.
+*
+* @param yaml - YAML string containing session transcript
+* @returns Parsed and validated SessionTranscript
+* @throws Error if YAML is invalid or doesn't match schema
+*/
+function parseSession(yaml) {
+	let raw;
+	try {
+		raw = YAML.parse(yaml);
+	} catch (err) {
+		throw new Error(`Failed to parse session YAML: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	const converted = toCamelCaseDeep(raw);
+	const result = SessionTranscriptSchema.safeParse(converted);
+	if (!result.success) {
+		const errors = result.error.errors.map((e) => `${e.path.join(".")}: ${e.message}`).join("; ");
+		throw new Error(`Invalid session transcript: ${errors}`);
+	}
+	return result.data;
+}
+/**
+* Serialize a session transcript to YAML string.
+*
+* Converts camelCase keys to snake_case for YAML output.
+*
+* @param session - Session transcript to serialize
+* @returns YAML string
+*/
+function serializeSession(session) {
+	const snakeCased = toSnakeCaseDeep(session);
+	return YAML.stringify(snakeCased, {
+		indent: 2,
+		lineWidth: 0
+	});
+}
+/**
+* Convert a string from snake_case to camelCase.
+*/
+function snakeToCamel(str) {
+	return str.replace(/_([a-z])/g, (_match, letter) => letter.toUpperCase());
+}
+/**
+* Convert a string from camelCase to snake_case.
+*/
+function camelToSnake(str) {
+	return str.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
+}
+/**
+* Recursively convert all object keys from snake_case to camelCase.
+*
+* Preserves keys that are user-defined identifiers (like option IDs in
+* checkboxes `values` objects).
+*
+* @param obj - Object to convert
+* @param preserveKeys - If true, don't convert keys in this object (but still recurse into values)
+*/
+function toCamelCaseDeep(obj, preserveKeys = false) {
+	if (obj === null || obj === void 0) return obj;
+	if (Array.isArray(obj)) return obj.map((item) => toCamelCaseDeep(item, false));
+	if (typeof obj === "object") {
+		const result = {};
+		const record = obj;
+		for (const [key, value] of Object.entries(record)) {
+			const resultKey = preserveKeys ? key : snakeToCamel(key);
+			result[resultKey] = toCamelCaseDeep(value, key === "values" && record.op === "set_checkboxes");
+		}
+		return result;
+	}
+	return obj;
+}
+/**
+* Recursively convert all object keys from camelCase to snake_case.
+*
+* Preserves keys that are user-defined identifiers (like option IDs in
+* checkboxes `values` objects).
+*
+* @param obj - Object to convert
+* @param preserveKeys - If true, don't convert keys in this object (but still recurse into values)
+*/
+function toSnakeCaseDeep(obj, preserveKeys = false) {
+	if (obj === null || obj === void 0) return obj;
+	if (Array.isArray(obj)) return obj.map((item) => toSnakeCaseDeep(item, false));
+	if (typeof obj === "object") {
+		const result = {};
+		const record = obj;
+		for (const [key, value] of Object.entries(record)) {
+			const resultKey = preserveKeys ? key : camelToSnake(key);
+			result[resultKey] = toSnakeCaseDeep(value, key === "values" && record.op === "set_checkboxes");
+		}
+		return result;
+	}
+	return obj;
+}
+
+//#endregion
+export { serializeSession as n, parseSession as t };

package/dist/session-DdAtY2Ni.mjs

@@ -0,0 +1,4 @@
+import "./coreTypes-Dful87E0.mjs";
+import { n as serializeSession, t as parseSession } from "./session-Bqnwi9wp.mjs";
+
+export { serializeSession };

package/dist/shared-D7gf27Tr.mjs

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