explorbot 0.1.31 → 0.2.0

package/dist/src/utils/aria.d.ts

@@ -0,0 +1,25 @@
+export interface FocusAreaResult {
+    detected: boolean;
+    type: 'dialog' | 'modal' | null;
+    name: string | null;
+}
+export declare const compactAriaSnapshot: (snapshot: string | null, keepNamed?: boolean) => string;
+export declare const diffAriaSnapshots: (previous: string | null, current: string | null) => AriaDiff;
+export declare const detectFocusArea: (snapshot: string | null) => FocusAreaResult;
+export declare const collectInteractiveNodes: (snapshot: string | null) => Array<Record<string, unknown>>;
+export interface FocusedElementInfo {
+    role: string;
+    name: string;
+    value?: string;
+    attributes?: string[];
+}
+export declare function extractFocusedElement(ariaSnapshot: string | null): FocusedElementInfo | null;
+export declare function parseAriaLocator(ariaStr: string): {
+    role: string;
+    text: string;
+} | null;
+export declare const LARGE_ARIA_CHANGE_THRESHOLD = 50;
+export interface AriaDiff {
+    text: string | null;
+    count: number;
+}

package/dist/src/utils/aria.js

@@ -490,7 +490,9 @@ export const diffAriaSnapshots = (previous, current) => {
     const currTotals = countBy(curr.map((e) => e.summary));
     const byCount = diffByCount(prevTotals, currTotals);
     const renames = detectRenames(prev, curr, prevTotals, currTotals);
-    return formatDiff([...byCount.added, ...renames.added], [...byCount.removed, ...renames.removed], toggled);
+    const added = [...byCount.added, ...renames.added];
+    const removed = [...byCount.removed, ...renames.removed];
+    return { text: formatDiff(added, removed, toggled), count: added.length + removed.length + toggled.length };
 };
 export const detectFocusArea = (snapshot) => {
     let tree = parseSnapshot(snapshot);
@@ -543,3 +545,4 @@ export function parseAriaLocator(ariaStr) {
         return null;
     return { role: match[1], text: match[2] };
 }
+export const LARGE_ARIA_CHANGE_THRESHOLD = 50;

package/dist/src/utils/browser-errors.d.ts

@@ -0,0 +1,8 @@
+export declare class BrowserRecoveryError extends Error {
+    originalError: unknown;
+    recovered: boolean;
+    constructor(label: string, originalError: unknown, recovered: boolean);
+}
+export declare function isFatalBrowserError(error: unknown): boolean;
+export declare function isNavigationTransitionError(error: unknown): boolean;
+export declare function browserErrorMessage(error: unknown): string;

package/dist/src/utils/cache.d.ts

@@ -0,0 +1,15 @@
+export declare class TTLCache<T> {
+    store: Map<string, CacheEntry<T>>;
+    ttlMs: number;
+    constructor(ttlMs?: number);
+    get(key: string): T | undefined;
+    set(key: string, value: T): void;
+    fetch(key: string, compute: () => Promise<T>): Promise<T>;
+    delete(key: string): void;
+    clear(): void;
+}
+type CacheEntry<T> = {
+    value: T;
+    at: number;
+};
+export {};

package/dist/src/utils/cache.js

@@ -0,0 +1,34 @@
+export class TTLCache {
+    store = new Map();
+    ttlMs;
+    constructor(ttlMs = Number.POSITIVE_INFINITY) {
+        this.ttlMs = ttlMs;
+    }
+    get(key) {
+        const entry = this.store.get(key);
+        if (!entry)
+            return undefined;
+        if (Date.now() - entry.at > this.ttlMs) {
+            this.store.delete(key);
+            return undefined;
+        }
+        return entry.value;
+    }
+    set(key, value) {
+        this.store.set(key, { value, at: Date.now() });
+    }
+    async fetch(key, compute) {
+        const cached = this.get(key);
+        if (cached !== undefined)
+            return cached;
+        const value = await compute();
+        this.set(key, value);
+        return value;
+    }
+    delete(key) {
+        this.store.delete(key);
+    }
+    clear() {
+        this.store.clear();
+    }
+}

package/dist/src/utils/cli-name.d.ts

@@ -0,0 +1 @@
+export declare function getCliName(): string;

package/dist/src/utils/code-extractor.d.ts

@@ -0,0 +1 @@
+export declare function extractCodeBlocks(aiResponse: string): string[];

package/dist/src/utils/context-formatter.d.ts

@@ -0,0 +1,31 @@
+export interface ContextData {
+    url: string;
+    title?: string;
+    headings: {
+        h1?: string;
+        h2?: string;
+        h3?: string;
+        h4?: string;
+    };
+    experience: Array<{
+        filePath: string;
+        data: any;
+        content: string;
+    }>;
+    knowledge: Array<{
+        filePath: string;
+        url: string;
+        content: string;
+    }>;
+    ariaSnapshot: string | null;
+    combinedHtml?: string;
+    research?: string;
+}
+export declare function formatHeadings(headings: {
+    h1?: string;
+    h2?: string;
+    h3?: string;
+    h4?: string;
+}): string[];
+export type ContextMode = 'attached' | 'compact' | 'full';
+export declare function formatContextSummary(data: ContextData, mode?: ContextMode): string;

package/dist/src/utils/context-formatter.js

@@ -10,6 +10,18 @@ function indent(text) {
         .map((line) => chalk.gray(`    ${line}`))
         .join('\n');
 }
+export function formatHeadings(headings) {
+    const lines = [];
+    if (headings.h1)
+        lines.push(`H1: ${headings.h1}`);
+    if (headings.h2)
+        lines.push(`H2: ${headings.h2}`);
+    if (headings.h3)
+        lines.push(`H3: ${headings.h3}`);
+    if (headings.h4)
+        lines.push(`H4: ${headings.h4}`);
+    return lines;
+}
 export function formatContextSummary(data, mode = 'compact') {
     if (mode === 'full') {
         return formatContextFull(data);
@@ -27,15 +39,7 @@ function formatContextAttached(data) {
         lines.push(indent(data.title));
     }
     lines.push('');
-    const headingLines = [];
-    if (data.headings.h1)
-        headingLines.push(`H1: ${data.headings.h1}`);
-    if (data.headings.h2)
-        headingLines.push(`H2: ${data.headings.h2}`);
-    if (data.headings.h3)
-        headingLines.push(`H3: ${data.headings.h3}`);
-    if (data.headings.h4)
-        headingLines.push(`H4: ${data.headings.h4}`);
+    const headingLines = formatHeadings(data.headings);
     if (headingLines.length > 0) {
         lines.push(section('HEADINGS') + chalk.gray(' (Auto-attached)'));
         lines.push(indent(headingLines.join('\n')));
@@ -88,15 +92,7 @@ function formatContextCompact(data) {
         lines.push(indent(data.title));
     }
     lines.push('');
-    const headingLines = [];
-    if (data.headings.h1)
-        headingLines.push(`H1: ${data.headings.h1}`);
-    if (data.headings.h2)
-        headingLines.push(`H2: ${data.headings.h2}`);
-    if (data.headings.h3)
-        headingLines.push(`H3: ${data.headings.h3}`);
-    if (data.headings.h4)
-        headingLines.push(`H4: ${data.headings.h4}`);
+    const headingLines = formatHeadings(data.headings);
     if (headingLines.length > 0) {
         lines.push(section('HEADINGS') + chalk.gray(' (Auto-attached)'));
         lines.push(indent(headingLines.join('\n')));
@@ -144,15 +140,7 @@ function formatContextFull(data) {
         lines.push(indent(data.title));
     }
     lines.push('');
-    const headingLines = [];
-    if (data.headings.h1)
-        headingLines.push(`H1: ${data.headings.h1}`);
-    if (data.headings.h2)
-        headingLines.push(`H2: ${data.headings.h2}`);
-    if (data.headings.h3)
-        headingLines.push(`H3: ${data.headings.h3}`);
-    if (data.headings.h4)
-        headingLines.push(`H4: ${data.headings.h4}`);
+    const headingLines = formatHeadings(data.headings);
     if (headingLines.length > 0) {
         lines.push(section('HEADINGS') + chalk.gray(' (Auto-attached)'));
         lines.push(indent(headingLines.join('\n')));

package/dist/src/utils/error-page.d.ts

@@ -0,0 +1,12 @@
+import { ActionResult } from '../action-result.js';
+import type { WebPageState } from '../state-manager.js';
+export type PageCondition = 'ok' | 'loading' | 'error';
+export declare function detectPageCondition(actionResult: ActionResult): PageCondition;
+export declare function isErrorPage(actionResult: ActionResult): boolean;
+export declare function getStateErrorPageError(state: WebPageState | null | undefined): ErrorPageError | null;
+export declare class ErrorPageError extends Error {
+    readonly url: string;
+    readonly title?: string;
+    readonly httpStatus?: number;
+    constructor(url: string, title?: string, httpStatus?: number);
+}

package/dist/src/utils/expandable.d.ts

@@ -0,0 +1,4 @@
+export declare const EXPANDABLE_ICON_DESCRIPTIONS: string[];
+export declare const EXPANDABLE_XPATHS: string[];
+export declare function buildExpandableXPath(excludeContainers?: string[]): string;
+export declare function buildExpandableXPathInsideContainers(containers: string[]): string[];

package/dist/src/utils/hooks-runner.d.ts

@@ -0,0 +1,15 @@
+import type { ExplorbotConfig, Hook, HookConfig } from '../config.js';
+import type Explorer from '../explorer.js';
+export declare class HooksRunner {
+    explorer: Explorer;
+    config: ExplorbotConfig;
+    constructor(explorer: Explorer, config: ExplorbotConfig);
+    runBeforeHook(agentName: string, url: string): Promise<void>;
+    runAfterHook(agentName: string, url: string): Promise<void>;
+    runHook(agentName: string, hookType: 'beforeHook' | 'afterHook', url: string): Promise<void>;
+    findMatchingHook(config: HookConfig, url: string): Hook | null;
+    patternSpecificity(pattern: string): number;
+    executeHook(hook: Hook, url: string): Promise<void>;
+    isSingleHook(config: HookConfig): boolean;
+    extractPath(url: string): string;
+}

package/dist/src/utils/html-diff.d.ts

@@ -0,0 +1,19 @@
+import type { HtmlConfig } from '../config.js';
+export interface HtmlDiffPart {
+    container: string;
+    subtree: string;
+    added: string[];
+    removed: string[];
+}
+export interface HtmlDiffResult {
+    parts: HtmlDiffPart[];
+    added: string[];
+    removed: string[];
+    similarity: number;
+    summary: string;
+}
+export declare function computeHtmlFingerprint(html: string): string[];
+/**
+ * Compares two HTML documents and returns differences along with a diff subtree.
+ */
+export declare function htmlDiff(originalHtml: string, modifiedHtml: string, htmlConfig?: HtmlConfig): Promise<HtmlDiffResult>;

package/dist/src/utils/html.d.ts

@@ -0,0 +1,129 @@
+import type * as parse5TreeAdapter from 'parse5/lib/tree-adapters/default';
+import type { HtmlConfig } from '../config.js';
+export declare const EXPLORBOT_ATTRS: {
+    readonly area: "data-explorbot-area";
+    readonly coveredBy: "data-explorbot-covered-by";
+    readonly context: "data-explorbot-context";
+    readonly eidx: "data-explorbot-eidx";
+    readonly hit: "data-explorbot-hit";
+    readonly variant: "data-explorbot-variant";
+};
+export declare const HTML_SELECTORS: {
+    readonly headingLabel: "h1, h2, h3, h4, h5, h6, legend, caption, label, [role=\"heading\"]";
+    readonly interactiveContent: "button, a[href], input, select, textarea, [role=\"button\"], [role=\"link\"], [role=\"option\"], [role=\"menuitem\"], [role=\"switch\"], [role=\"checkbox\"], [role=\"radio\"], [aria-label], [tabindex]";
+    readonly interactiveControl: "button, a[href], input, select, textarea, [role=\"button\"], [role=\"link\"], [role=\"checkbox\"], [role=\"radio\"], [role=\"switch\"], [role=\"tab\"], [role=\"menuitem\"]";
+    readonly labelLike: "h1, h2, h3, h4, h5, h6, legend, caption, label, [role=\"heading\"], [class*=\"title\"], [class*=\"label\"], [class*=\"header\"], [class*=\"name\"]";
+    readonly semanticContextContainer: "section, article, form, fieldset, li, tr, td, th, [role=\"group\"], [role=\"tabpanel\"], [role=\"region\"], [class*=\"card\"], [class*=\"panel\"], [class*=\"item\"], [class*=\"usage\"], [class*=\"group\"]";
+    readonly semanticOverlays: readonly ["[role=\"dialog\"]", "[role=\"listbox\"]", "[role=\"menu\"]", "[role=\"tooltip\"]:not([style*=\"display: none\"]):not([style*=\"visibility: hidden\"])"];
+};
+export declare const HTML_VISIBILITY_LIMITS: {
+    readonly maxViewportOverlayRatio: 0.95;
+    readonly minOpacity: 0.1;
+    readonly minOverlayHeight: 40;
+    readonly minOverlayWidth: 80;
+};
+export declare const HTML_EXTRACTION_LIMITS: {
+    readonly componentScopeHtmlLength: 8000;
+    readonly maxOverlayCount: 3;
+    readonly maxScopeInteractiveCount: 16;
+    readonly overlayHtmlLength: 6000;
+};
+export declare const CODE_EDITOR_MARKERS: readonly ["monaco", "codemirror", "ace", "ace_editor", "code"];
+export declare const HTML_INTERACTIVE_ROLES: Set<string>;
+export declare const HTML_FORM_CONTROL_ROLES: Set<string>;
+export declare const HTML_COMPOSITE_TARGET_ROLES: Set<string>;
+export declare const HTML_COMPOSITE_AREA_HINTS: Set<string>;
+export declare const HTML_FORM_CONTROL_TAGS: Set<string>;
+export declare function inferHtmlRole(data: {
+    attrs: Record<string, string>;
+    role?: string;
+    tag: string;
+    variantHints?: string[];
+}): string;
+export declare const ELEMENT_EXTRACTION_CONFIG: {
+    readonly attrs: {
+        readonly area: "data-explorbot-area";
+        readonly coveredBy: "data-explorbot-covered-by";
+        readonly context: "data-explorbot-context";
+        readonly eidx: "data-explorbot-eidx";
+        readonly hit: "data-explorbot-hit";
+        readonly variant: "data-explorbot-variant";
+    };
+    readonly codeEditorMarkers: readonly ["monaco", "codemirror", "ace", "ace_editor", "code"];
+    readonly maxAreaDepth: 5;
+    readonly maxContextLength: 120;
+    readonly maxOuterHTMLLength: 2000;
+    readonly maxTextLength: 80;
+    readonly minOpacity: 0.1;
+    readonly selectors: {
+        readonly headingLabel: "h1, h2, h3, h4, h5, h6, legend, caption, label, [role=\"heading\"]";
+        readonly labelLike: "h1, h2, h3, h4, h5, h6, legend, caption, label, [role=\"heading\"], [class*=\"title\"], [class*=\"label\"], [class*=\"header\"], [class*=\"name\"]";
+        readonly semanticContextContainer: "section, article, form, fieldset, li, tr, td, th, [role=\"group\"], [role=\"tabpanel\"], [role=\"region\"], [class*=\"card\"], [class*=\"panel\"], [class*=\"item\"], [class*=\"usage\"], [class*=\"group\"]";
+    };
+};
+export type ElementExtractionConfig = typeof ELEMENT_EXTRACTION_CONFIG;
+export type RawElementData = NonNullable<ReturnType<typeof extractElementData>>;
+export type VisibleOverlayExtractionConfig = {
+    interactiveContentSelector: string;
+    limits: typeof HTML_EXTRACTION_LIMITS;
+    overlaySelectors: readonly string[];
+    visibilityLimits: typeof HTML_VISIBILITY_LIMITS;
+};
+export type ComponentScopeExtractionConfig = {
+    eidxAttr: string;
+    interactiveControlSelector: string;
+    limits: typeof HTML_EXTRACTION_LIMITS;
+};
+export declare function captureHtmlForSnapshot(): string;
+export declare function extractElementData(el: Element, config?: ElementExtractionConfig): {
+    tag: string;
+    text: string;
+    allAttrs: Record<string, string>;
+    outerHTML: string;
+    x: number;
+    y: number;
+};
+export declare function getElementDataExtractorSource(): string;
+export declare function extractVisibleOverlayHtml(config: VisibleOverlayExtractionConfig): string;
+export declare function extractComponentScopeHtml(eidx: string, config: ComponentScopeExtractionConfig): string;
+export declare function getVisibleOverlayHtmlExtractorSource(): string;
+export declare function getComponentScopeHtmlExtractorSource(): string;
+export declare const TRASH_HTML_CLASSES: RegExp;
+export declare const TAILWIND_CLASS_PATTERNS: RegExp[];
+export declare function sanitizeHtmlDocument(html: string, htmlConfig?: HtmlConfig): parse5TreeAdapter.Document;
+export declare function sanitizeHtmlString(html: string, htmlConfig?: HtmlConfig): string;
+/**
+ * Creates a minimal snapshot keeping only interactive elements and their structure
+ * Based on CodeceptJS HTML library
+ */
+export declare function htmlMinimalUISnapshot(html: string, htmlConfig?: HtmlConfig['minimal']): string;
+export declare function minifyHtml(html: string): Promise<string>;
+/**
+ * Creates a combined snapshot with interactive elements and meaningful text
+ * Preserves original HTML structure
+ */
+export declare function htmlCombinedSnapshot(html: string, htmlConfig?: HtmlConfig['combined'], opts?: {
+    keepPositions?: boolean;
+}): string;
+/**
+ * Creates text-only snapshot with markdown formatting
+ */
+export declare function htmlTextSnapshot(html: string, htmlConfig?: HtmlConfig['text']): string;
+export interface ExtractedLink {
+    title: string;
+    url: string;
+}
+export declare function extractLinks(html: string): ExtractedLink[];
+export declare function extractHeadings(html: string): {
+    h1?: string;
+    h2?: string;
+    h3?: string;
+    h4?: string;
+};
+export declare function codeToMarkdown(code: string): string;
+export declare function isBodyEmpty(html: string): boolean;
+/**
+ * Extract HTML snippet around a targeted element based on locator
+ * Used for accessibility analysis to show what element was being targeted
+ */
+export declare function extractTargetedHtml(html: string, locator: string): string;

package/dist/src/utils/html.js

@@ -67,8 +67,10 @@ const INTERACTIVE_EVENT_ATTRIBUTES = new Set(['onclick', 'onchange', 'onblur', '
 const HIDDEN_CLASSES = new Set(['hidden', 'invisible', 'd-none', 'hide', 'dn', 'u-hidden', 'is-hidden', 'visually-hidden', 'sr-only', 'screen-reader-only', 'visuallyhidden', 'opacity-0']);
 export const EXPLORBOT_ATTRS = {
     area: 'data-explorbot-area',
+    coveredBy: 'data-explorbot-covered-by',
     context: 'data-explorbot-context',
     eidx: 'data-explorbot-eidx',
+    hit: 'data-explorbot-hit',
     variant: 'data-explorbot-variant',
 };
 export const HTML_SELECTORS = {
@@ -139,13 +141,41 @@ export const ELEMENT_EXTRACTION_CONFIG = {
         semanticContextContainer: HTML_SELECTORS.semanticContextContainer,
     },
 };
+export function captureHtmlForSnapshot() {
+    const clone = document.documentElement.cloneNode(true);
+    const liveControls = Array.from(document.querySelectorAll('input, textarea, select'));
+    const clonedControls = Array.from(clone.querySelectorAll('input, textarea, select'));
+    for (let i = 0; i < liveControls.length; i++) {
+        const source = liveControls[i];
+        const target = clonedControls[i];
+        if (!target)
+            continue;
+        if (source instanceof HTMLInputElement || source instanceof HTMLTextAreaElement) {
+            target.setAttribute('data-explorbot-value', source.value);
+        }
+        if (source instanceof HTMLInputElement && (source.type === 'checkbox' || source.type === 'radio')) {
+            let checked = 'false';
+            if (source.checked)
+                checked = 'true';
+            target.setAttribute('data-explorbot-checked', checked);
+        }
+        if (source instanceof HTMLSelectElement) {
+            target.setAttribute('data-explorbot-value', Array.from(source.selectedOptions)
+                .map((option) => option.value)
+                .join(','));
+        }
+    }
+    return clone.outerHTML;
+}
 export function extractElementData(el, config) {
     const cfg = config ||
         {
             attrs: {
                 area: 'data-explorbot-area',
+                coveredBy: 'data-explorbot-covered-by',
                 context: 'data-explorbot-context',
                 eidx: 'data-explorbot-eidx',
+                hit: 'data-explorbot-hit',
                 variant: 'data-explorbot-variant',
             },
             codeEditorMarkers: ['monaco', 'codemirror', 'ace', 'ace_editor', 'code'],
@@ -223,6 +253,43 @@ export function extractElementData(el, config) {
             tokens.add('navigates');
         return Array.from(tokens).slice(0, 8);
     }
+    function describeOverlappingElement(target) {
+        const parts = [target.tagName.toLowerCase()];
+        const role = target.getAttribute('role');
+        const ariaLabel = target.getAttribute('aria-label');
+        const id = target.getAttribute('id');
+        const className = (target.getAttribute('class') || '').split(/\s+/).filter(Boolean).slice(0, 3).join('.');
+        if (id)
+            parts.push(`#${id.slice(0, 40)}`);
+        if (className)
+            parts.push(`.${className.slice(0, 80)}`);
+        if (role)
+            parts.push(`[role="${role.slice(0, 40)}"]`);
+        if (ariaLabel)
+            parts.push(`[aria-label="${ariaLabel.slice(0, 80)}"]`);
+        return parts.join('');
+    }
+    function inspectHitTarget(target, rect) {
+        const viewportPoints = [
+            { x: rect.left + rect.width / 2, y: rect.top + rect.height / 2 },
+            { x: rect.left + Math.min(rect.width - 1, Math.max(1, rect.width * 0.25)), y: rect.top + Math.min(rect.height - 1, Math.max(1, rect.height * 0.25)) },
+            { x: rect.left + Math.min(rect.width - 1, Math.max(1, rect.width * 0.75)), y: rect.top + Math.min(rect.height - 1, Math.max(1, rect.height * 0.75)) },
+        ].filter((point) => point.x >= 0 && point.y >= 0 && point.x <= window.innerWidth && point.y <= window.innerHeight);
+        if (viewportPoints.length === 0) {
+            return { hit: 'offscreen' };
+        }
+        for (const point of viewportPoints) {
+            const top = document.elementFromPoint(point.x, point.y);
+            if (!top)
+                continue;
+            if (top === target || target.contains(top)) {
+                return { hit: 'target' };
+            }
+        }
+        const centerPoint = viewportPoints[0];
+        const top = document.elementFromPoint(centerPoint.x, centerPoint.y);
+        return { hit: 'covered', coveredBy: top ? describeOverlappingElement(top) : undefined };
+    }
     function isEmbeddedCodeEditorFrame(target) {
         const src = (target.getAttribute('src') || '').toLowerCase();
         const markerSelector = cfg.codeEditorMarkers.map((marker) => `[class*="${marker}"]`).join(', ');
@@ -329,6 +396,10 @@ export function extractElementData(el, config) {
     allAttrs[cfg.attrs.area] = areaHints.join('|');
     allAttrs[cfg.attrs.context] = findContextLabel(el);
     allAttrs[cfg.attrs.variant] = collectVariantHints(el).join('|');
+    const hitTarget = inspectHitTarget(el, rect);
+    allAttrs[cfg.attrs.hit] = hitTarget.hit;
+    if (hitTarget.coveredBy)
+        allAttrs[cfg.attrs.coveredBy] = hitTarget.coveredBy;
     return {
         tag: el.tagName.toLowerCase(),
         text: normalizeText(el.textContent || '').slice(0, cfg.maxTextLength),

package/dist/src/utils/log-filters.d.ts

@@ -0,0 +1,6 @@
+export declare class RecentStepFilter {
+    ttlMs: number;
+    recentStepKeys: Map<string, number>;
+    constructor(ttlMs?: number);
+    shouldSuppress(content: string, now?: number): boolean;
+}

package/dist/src/utils/logger.d.ts

@@ -0,0 +1,35 @@
+import { type Span } from '@opentelemetry/api';
+export type LogType = 'info' | 'success' | 'error' | 'warning' | 'debug' | 'substep' | 'operation' | 'step' | 'multiline' | 'details' | 'html' | 'input';
+export interface TaggedLogEntry {
+    type: LogType;
+    content: string;
+    timestamp?: Date;
+    originalArgs?: any[];
+    namespace?: string;
+    maxLines?: number;
+}
+type LogEntry = TaggedLogEntry;
+export declare const tag: (type: LogType) => {
+    log: (...args: any[]) => void;
+};
+export declare const log: (...args: any[]) => void;
+export declare const logSuccess: (...args: any[]) => void;
+export declare const logError: (...args: any[]) => void;
+export declare const logWarning: (...args: any[]) => void;
+export declare const logSubstep: (...args: any[]) => void;
+export declare const createDebug: (namespace: string) => (...args: any[]) => void;
+export declare const getMethodsOfObject: (obj: any) => string[];
+export declare const startLogCapture: () => void;
+export declare const stopLogCapture: () => string[];
+export declare const setVerboseMode: (enabled: boolean) => void;
+export declare const setPreserveConsoleLogs: (enabled: boolean) => void;
+export declare const isVerboseMode: () => boolean;
+export declare const setDebugMode: (enabled: boolean) => void;
+export declare const isDebugMode: () => boolean;
+export declare const registerLogPane: (addLog: (entry: LogEntry) => void) => void;
+export declare const unregisterLogPane: (addLog: (entry: LogEntry) => void) => void;
+export declare const addTruncateTag: (tagName: string) => void;
+export declare const setStepSpanParent: (span: Span | null) => void;
+export declare const setLogCallback: (addLog: (entry: LogEntry) => void) => void;
+export declare const pluralize: (count: number, singular: string, plural?: string) => string;
+export {};

package/dist/src/utils/loop.d.ts

@@ -0,0 +1,35 @@
+export declare class StopError extends Error {
+    constructor(message?: string);
+}
+export declare class InterruptError extends Error {
+    userInput: string | null;
+    constructor(userInput: string | null);
+}
+export interface LoopContext {
+    stop: () => void;
+    iteration: number;
+    pause: (prompt?: string) => Promise<string | null>;
+    userInput: string | null;
+    setUserInput: (input: string) => void;
+}
+export interface CatchContext {
+    error: Error;
+    stop: () => void;
+    iteration: number;
+}
+export interface LoopOptions {
+    maxAttempts?: number;
+    interruptible?: boolean;
+    interruptPrompt?: string;
+    onInterrupt?: (userInput: string | null, context: LoopContext) => Promise<void> | void;
+    catch?: (context: CatchContext) => Promise<void> | void;
+    observability?: {
+        name?: string;
+        agent?: string;
+        sessionId?: string;
+        tags?: string[];
+        metadata?: Record<string, unknown>;
+    };
+}
+export declare function pause(prompt?: string): Promise<string | null>;
+export declare function loop<T>(handler: (context: LoopContext) => Promise<T>, options?: LoopOptions): Promise<any>;

package/dist/src/utils/markdown-files.d.ts

@@ -0,0 +1,10 @@
+export declare function loadMarkdownFiles(dir: string, options?: {
+    recursive?: boolean;
+    onError?: (filePath: string, error: unknown) => void;
+}): MarkdownFile[];
+export interface MarkdownFile {
+    filePath: string;
+    content: string;
+    data: Record<string, any>;
+    mtime: Date;
+}

package/dist/src/utils/markdown-files.js

@@ -0,0 +1,21 @@
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import matter from 'gray-matter';
+export function loadMarkdownFiles(dir, options = {}) {
+    if (!existsSync(dir))
+        return [];
+    const results = [];
+    const files = readdirSync(dir, { recursive: options.recursive === true })
+        .filter((file) => typeof file === 'string' && file.endsWith('.md'))
+        .map((file) => join(dir, file));
+    for (const filePath of files) {
+        try {
+            const parsed = matter(readFileSync(filePath, 'utf8'));
+            results.push({ filePath, content: parsed.content, data: parsed.data, mtime: statSync(filePath).mtime });
+        }
+        catch (error) {
+            options.onError?.(filePath, error);
+        }
+    }
+    return results;
+}

package/dist/src/utils/markdown-parser.d.ts

@@ -0,0 +1,17 @@
+export interface MarkdownSection {
+    name: string;
+    depth: number;
+    rawMarkdown: string;
+}
+export declare function parseSections(markdown: string, opts?: {
+    minDepth?: number;
+    maxDepth?: number;
+}): MarkdownSection[];
+export declare function extractLabeledCode(markdown: string, labelPattern: RegExp): string | null;
+export declare function tableToJson(markdown: string): Record<string, string>[];
+export declare function jsonToTable(rows: Record<string, string>[], columns?: string[]): string;
+export declare function findTableRaw(markdown: string): string | null;
+export declare function findTableLineRange(markdown: string): {
+    start: number;
+    end: number;
+} | null;