byterover-cli 2.0.0 → 2.1.1

package/dist/agent/infra/map/llm-map-service.js

@@ -0,0 +1,118 @@
+import { writeFile } from 'node:fs/promises';
+import { buildRetryMessage, buildUserMessage, callLlm, parseJsonlFile, resolveAndValidatePath, validateAgainstSchema, withTimeout, } from './map-shared.js';
+import { runMapWorkerPool } from './worker-pool.js';
+// ── LLM-Map Service ──────────────────────────────────────────────────────────
+/**
+ * Execute an LLM-Map: parallel, stateless LLM calls over a JSONL file.
+ *
+ * For each item (line), makes a single LLM API call (no tools, no file I/O)
+ * that must return one JSON value conforming to the provided output schema.
+ * If validation fails, the system retries with the error and prior response.
+ *
+ * Ported from VoltCode's llm-map.ts, adapted for byterover-cli:
+ * - Uses IContentGenerator instead of AI SDK's generateText()
+ * - Uses in-memory worker pool (no FileMapStore / PostgreSQL)
+ * - Runs in-process (no SQS)
+ */
+export async function executeLlmMap(options) {
+    const { abortSignal, generator, onProgress, params, taskId, workingDirectory, } = options;
+    const { concurrency = 8, input_path: inputPath, max_attempts: maxAttempts = 3, output_path: outputPath, output_schema: outputSchema, prompt, timeout_seconds: timeoutSeconds = 120, } = params;
+    // Resolve paths relative to working directory and validate they don't escape it
+    const resolvedInputPath = resolveAndValidatePath(workingDirectory, inputPath);
+    const resolvedOutputPath = resolveAndValidatePath(workingDirectory, outputPath);
+    // 1. Parse input JSONL
+    const items = await parseJsonlFile(resolvedInputPath);
+    if (items.length === 0) {
+        // Write empty output file
+        await writeFile(resolvedOutputPath, '', 'utf8');
+        return { failed: 0, mapId: 'empty', succeeded: 0, total: 0 };
+    }
+    // 2. Prepare run metadata
+    const runStartedAt = new Date().toISOString();
+    // 3. Define per-item processing function
+    async function processItem(itemIndex, item) {
+        const userMessage = buildUserMessage(prompt, 'pending', runStartedAt, itemIndex, item, outputSchema);
+        // Per-item timeout
+        const timeoutController = new AbortController();
+        const timeoutHandle = setTimeout(() => {
+            timeoutController.abort();
+        }, timeoutSeconds * 1000);
+        try {
+            let attemptsUsed = 1;
+            let lastResponse = '';
+            let lastError = '';
+            // Initial LLM call (stateless — no tool access)
+            // Wrap with timeout so a hung generateContent() doesn't block forever
+            const response = await withTimeout(callLlm(generator, userMessage, taskId, abortSignal), timeoutController.signal);
+            lastResponse = response.content;
+            // Validation loop with retry
+            while (true) {
+                // Try to parse JSON
+                let parsed;
+                try {
+                    parsed = JSON.parse(lastResponse);
+                }
+                catch (error) {
+                    lastError = `JSON parse error: ${error instanceof Error ? error.message : String(error)}`;
+                }
+                // Validate against schema
+                if (parsed !== undefined) {
+                    const validation = validateAgainstSchema(parsed, outputSchema);
+                    if (validation.valid) {
+                        // Fail-open: store result in context tree if available
+                        if (options.contextTreeStore) {
+                            try {
+                                options.contextTreeStore.store(itemIndex, JSON.stringify(parsed));
+                            }
+                            catch (storeError) {
+                                options.logger?.warn('Context tree store failed', { error: String(storeError), itemIndex });
+                            }
+                        }
+                        return parsed;
+                    }
+                    lastError = `Schema validation failed: ${validation.error}`;
+                }
+                // Check retry budget
+                if (attemptsUsed >= maxAttempts) {
+                    throw new Error(`Failed after ${attemptsUsed} attempts. Last error: ${lastError}`);
+                }
+                // Check abort or timeout
+                if (abortSignal?.aborted || timeoutController.signal.aborted) {
+                    throw new Error('Aborted or timed out');
+                }
+                // Retry with error context + prior response
+                attemptsUsed++;
+                const retryMessage = buildRetryMessage(userMessage, lastError, lastResponse);
+                // eslint-disable-next-line no-await-in-loop
+                const retryResponse = await withTimeout(callLlm(generator, retryMessage, taskId, abortSignal), timeoutController.signal);
+                lastResponse = retryResponse.content;
+            }
+        }
+        finally {
+            clearTimeout(timeoutHandle);
+        }
+    }
+    // 4. Run in-memory worker pool
+    const result = await runMapWorkerPool({
+        abortSignal,
+        concurrency,
+        items,
+        onProgress,
+        processItem,
+    });
+    // 5. Compact context tree and attach summaryHandle (fail-open)
+    if (options.contextTreeStore) {
+        try {
+            await options.contextTreeStore.compact();
+            result.summaryHandle = options.contextTreeStore.getSummaryHandle();
+        }
+        catch (compactError) {
+            options.logger?.warn('Context tree compaction failed', { error: String(compactError) });
+        }
+    }
+    // 6. Write output JSONL from in-memory results (sorted by index)
+    const sorted = [...result.results.entries()].sort(([a], [b]) => a - b);
+    const outputContent = sorted.map(([, r]) => JSON.stringify(r)).join('\n');
+    await writeFile(resolvedOutputPath, outputContent, 'utf8');
+    return result;
+}

package/dist/agent/infra/map/map-shared.d.ts

@@ -0,0 +1,140 @@
+import { z } from 'zod';
+import type { GenerateContentResponse, IContentGenerator } from '../../core/interfaces/i-content-generator.js';
+/**
+ * Canonicalize a path by resolving symlinks.
+ * For existing paths, uses realpathSync.native().
+ * For non-existent paths (e.g., output files), walks up to the nearest
+ * existing ancestor directory, canonicalizes it, then reconstructs the
+ * remaining non-existent segments on top. This catches symlink escapes
+ * at any depth (e.g., workspace/symlink-to-outside/new-dir/file.jsonl).
+ */
+/**
+ * Export the canonical path resolver for use in anti-cycle checks.
+ * Returns the real path via realpathSync.native(); falls back to walking
+ * up to the nearest existing ancestor for non-existent paths.
+ */
+export declare function canonicalizePath(absolutePath: string): string;
+/**
+ * Resolve a path relative to the working directory and validate it stays within bounds.
+ * Prevents both path traversal (e.g., `../../etc/passwd`) and symlink escape
+ * (e.g., a symlink under the repo pointing to an external location).
+ *
+ * @throws Error if the resolved path escapes the working directory
+ */
+export declare function resolveAndValidatePath(workingDirectory: string, filePath: string): string;
+/**
+ * Deterministic JSON serialization with recursively sorted keys.
+ * Ensures identical output regardless of key insertion order.
+ *
+ * Ported from VoltCode's map-shared.ts.
+ */
+export declare function stableStringify(value: unknown): string;
+/**
+ * Build the user message with prompt + `<map-details-json>` block.
+ * Each item gets a deterministic metadata block for reproducibility.
+ */
+export declare function buildUserMessage(promptText: string, mapId: string, runStartedAt: string, itemIndex: number, item: unknown, outputSchema: Record<string, unknown>): string;
+/**
+ * Build a retry message that includes the original prompt, the error, and the prior response.
+ */
+export declare function buildRetryMessage(originalUserMessage: string, error: string, priorResponse: string): string;
+/**
+ * Parse a JSONL file into an array of JSON values.
+ * Each line must be valid JSON. Empty trailing lines are tolerated.
+ */
+export declare function parseJsonlFile(filePath: string): Promise<unknown[]>;
+/**
+ * Write items as a JSONL file. Each item is serialized to one line.
+ */
+export declare function itemsToJsonl(items: unknown[]): string;
+/**
+ * Validate a parsed value against a JSON Schema using Zod passthrough.
+ * Returns {valid: true, value} on success, {valid: false, error} on failure.
+ *
+ * For simplicity, we use a basic JSON Schema validation approach rather than
+ * requiring ajv as a dependency. The schema is used mainly for type checking
+ * (object with expected properties).
+ */
+export declare function validateAgainstSchema(value: unknown, schema: Record<string, unknown>): {
+    error?: string;
+    valid: boolean;
+};
+export declare const LlmMapParametersSchema: z.ZodObject<{
+    concurrency: z.ZodOptional<z.ZodNumber>;
+    input_path: z.ZodString;
+    max_attempts: z.ZodOptional<z.ZodNumber>;
+    output_path: z.ZodString;
+    output_schema: z.ZodRecord<z.ZodString, z.ZodAny>;
+    prompt: z.ZodString;
+    timeout_seconds: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    prompt: string;
+    output_schema: Record<string, any>;
+    input_path: string;
+    output_path: string;
+    concurrency?: number | undefined;
+    max_attempts?: number | undefined;
+    timeout_seconds?: number | undefined;
+}, {
+    prompt: string;
+    output_schema: Record<string, any>;
+    input_path: string;
+    output_path: string;
+    concurrency?: number | undefined;
+    max_attempts?: number | undefined;
+    timeout_seconds?: number | undefined;
+}>;
+export type LlmMapParameters = z.infer<typeof LlmMapParametersSchema>;
+export declare const AgenticMapParametersSchema: z.ZodObject<{
+    input_path: z.ZodString;
+    max_attempts: z.ZodOptional<z.ZodNumber>;
+    max_depth: z.ZodOptional<z.ZodNumber>;
+    output_path: z.ZodString;
+    output_schema: z.ZodRecord<z.ZodString, z.ZodAny>;
+    prompt: z.ZodString;
+    read_only: z.ZodOptional<z.ZodBoolean>;
+    timeout_seconds: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    prompt: string;
+    output_schema: Record<string, any>;
+    input_path: string;
+    output_path: string;
+    max_attempts?: number | undefined;
+    timeout_seconds?: number | undefined;
+    max_depth?: number | undefined;
+    read_only?: boolean | undefined;
+}, {
+    prompt: string;
+    output_schema: Record<string, any>;
+    input_path: string;
+    output_path: string;
+    max_attempts?: number | undefined;
+    timeout_seconds?: number | undefined;
+    max_depth?: number | undefined;
+    read_only?: boolean | undefined;
+}>;
+export type AgenticMapParameters = z.infer<typeof AgenticMapParametersSchema>;
+/**
+ * System message for LLM-Map: enforces stateless JSON-only output.
+ */
+export declare const LLM_MAP_SYSTEM_MESSAGE: string;
+/**
+ * System message for Agentic-Map: allows tool access with JSON output.
+ */
+export declare function buildAgenticMapSystemMessage(readOnly: boolean): string;
+/**
+ * Build the recursive composition guidance block appended to sub-agent user messages
+ * when this depth level allows further nesting.
+ */
+export declare function buildRecursiveCompositionGuidance(currentDepth: number, maxDepth: number): string;
+/**
+ * Race a promise against an abort signal.
+ * Used across map services to enforce per-item timeouts on calls that
+ * don't natively accept AbortSignal (e.g., generateContent, executeOnSession).
+ */
+export declare function withTimeout<T>(promise: Promise<T>, signal: AbortSignal): Promise<T>;
+/**
+ * Stateless LLM call for map item processing.
+ * Shared by llm-map-service and llm-map-memory.
+ */
+export declare function callLlm(generator: IContentGenerator, userMessage: string, taskId?: string, abortSignal?: AbortSignal): Promise<GenerateContentResponse>;

package/dist/agent/infra/map/map-shared.js

@@ -0,0 +1,325 @@
+/* eslint-disable camelcase */
+import { randomUUID } from 'node:crypto';
+import { realpathSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { basename, dirname, join, normalize, resolve, sep } from 'node:path';
+import { z } from 'zod';
+// ── Path Safety ─────────────────────────────────────────────────────────────
+/**
+ * Canonicalize a path by resolving symlinks.
+ * For existing paths, uses realpathSync.native().
+ * For non-existent paths (e.g., output files), walks up to the nearest
+ * existing ancestor directory, canonicalizes it, then reconstructs the
+ * remaining non-existent segments on top. This catches symlink escapes
+ * at any depth (e.g., workspace/symlink-to-outside/new-dir/file.jsonl).
+ */
+/**
+ * Export the canonical path resolver for use in anti-cycle checks.
+ * Returns the real path via realpathSync.native(); falls back to walking
+ * up to the nearest existing ancestor for non-existent paths.
+ */
+export function canonicalizePath(absolutePath) {
+    return canonicalize(absolutePath);
+}
+function canonicalize(absolutePath) {
+    try {
+        return realpathSync.native(absolutePath);
+    }
+    catch {
+        // Path doesn't exist — recurse up to the nearest existing ancestor
+        const dir = dirname(absolutePath);
+        const base = basename(absolutePath);
+        // Guard: reached filesystem root without finding an existing path
+        if (dir === absolutePath) {
+            return normalize(absolutePath);
+        }
+        return join(canonicalize(dir), base);
+    }
+}
+/**
+ * Resolve a path relative to the working directory and validate it stays within bounds.
+ * Prevents both path traversal (e.g., `../../etc/passwd`) and symlink escape
+ * (e.g., a symlink under the repo pointing to an external location).
+ *
+ * @throws Error if the resolved path escapes the working directory
+ */
+export function resolveAndValidatePath(workingDirectory, filePath) {
+    const resolved = resolve(workingDirectory, filePath);
+    // Canonicalize both paths to resolve symlinks before containment check
+    const canonicalRoot = canonicalize(resolve(workingDirectory));
+    const canonicalResolved = canonicalize(resolved);
+    if (!canonicalResolved.startsWith(canonicalRoot + sep) && canonicalResolved !== canonicalRoot) {
+        throw new Error(`Path "${filePath}" resolves outside the working directory`);
+    }
+    return resolved;
+}
+// ── Deterministic JSON Serialization ─────────────────────────────────────────
+/**
+ * Deterministic JSON serialization with recursively sorted keys.
+ * Ensures identical output regardless of key insertion order.
+ *
+ * Ported from VoltCode's map-shared.ts.
+ */
+export function stableStringify(value) {
+    return JSON.stringify(value, (_key, val) => {
+        if (val !== null && typeof val === 'object' && !Array.isArray(val)) {
+            const sorted = {};
+            for (const k of Object.keys(val).sort()) {
+                sorted[k] = val[k];
+            }
+            return sorted;
+        }
+        return val;
+    });
+}
+// ── User Message Builder ─────────────────────────────────────────────────────
+/**
+ * Build the user message with prompt + `<map-details-json>` block.
+ * Each item gets a deterministic metadata block for reproducibility.
+ */
+export function buildUserMessage(promptText, mapId, runStartedAt, itemIndex, item, outputSchema) {
+    const details = {
+        item,
+        item_index: itemIndex,
+        map_id: mapId,
+        output_schema: outputSchema,
+        run_started_at: runStartedAt,
+    };
+    return `${promptText}\n\n<map-details-json>\n${stableStringify(details)}\n</map-details-json>`;
+}
+/**
+ * Build a retry message that includes the original prompt, the error, and the prior response.
+ */
+export function buildRetryMessage(originalUserMessage, error, priorResponse) {
+    return [
+        originalUserMessage,
+        '',
+        '<map-retry>',
+        `Your previous response could not be used: ${error}`,
+        '',
+        'Your prior response was:',
+        priorResponse,
+        '',
+        'Please output corrected JSON only. No explanations, no markdown fences.',
+        '</map-retry>',
+    ].join('\n');
+}
+// ── JSONL Parsing ────────────────────────────────────────────────────────────
+/**
+ * Parse a JSONL file into an array of JSON values.
+ * Each line must be valid JSON. Empty trailing lines are tolerated.
+ */
+export async function parseJsonlFile(filePath) {
+    const rawText = await readFile(filePath, 'utf8');
+    const rawLines = rawText.split('\n');
+    const lines = rawLines.at(-1) === '' ? rawLines.slice(0, -1) : rawLines;
+    const items = [];
+    for (const [i, line] of lines.entries()) {
+        if (line.trim() === '') {
+            throw new Error(`Line ${i} is empty. Every line must be valid JSON.`);
+        }
+        try {
+            items.push(JSON.parse(line));
+        }
+        catch (error) {
+            throw new Error(`Line ${i} is not valid JSON: ${error}`);
+        }
+    }
+    return items;
+}
+/**
+ * Write items as a JSONL file. Each item is serialized to one line.
+ */
+export function itemsToJsonl(items) {
+    return items.map((item) => JSON.stringify(item)).join('\n');
+}
+// ── Schema Validation ────────────────────────────────────────────────────────
+/**
+ * Validate a parsed value against a JSON Schema using Zod passthrough.
+ * Returns {valid: true, value} on success, {valid: false, error} on failure.
+ *
+ * For simplicity, we use a basic JSON Schema validation approach rather than
+ * requiring ajv as a dependency. The schema is used mainly for type checking
+ * (object with expected properties).
+ */
+export function validateAgainstSchema(value, schema) {
+    // Basic type check
+    if (schema.type === 'object' && (typeof value !== 'object' || value === null || Array.isArray(value))) {
+        return { error: `Expected object, got ${typeof value}`, valid: false };
+    }
+    if (schema.type === 'array' && !Array.isArray(value)) {
+        return { error: `Expected array, got ${typeof value}`, valid: false };
+    }
+    if (schema.type === 'string' && typeof value !== 'string') {
+        return { error: `Expected string, got ${typeof value}`, valid: false };
+    }
+    if (schema.type === 'number' && typeof value !== 'number') {
+        return { error: `Expected number, got ${typeof value}`, valid: false };
+    }
+    // Check required properties for objects
+    if (schema.type === 'object' && schema.required && Array.isArray(schema.required)) {
+        const obj = value;
+        for (const key of schema.required) {
+            if (!(key in obj)) {
+                return { error: `Missing required property: ${key}`, valid: false };
+            }
+        }
+    }
+    return { valid: true };
+}
+// ── Zod Schemas for Map Tool Parameters ──────────────────────────────────────
+export const LlmMapParametersSchema = z.object({
+    concurrency: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe('Max parallel LLM requests (default: 8)'),
+    input_path: z.string().describe('File path to JSONL input'),
+    max_attempts: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe('Max LLM calls per item (default: 3)'),
+    output_path: z.string().describe('File path where JSONL output will be written'),
+    output_schema: z
+        .record(z.string(), z.any())
+        .describe('JSON Schema for LLM output validation'),
+    prompt: z.string().describe('Base instruction text sent to the LLM for each item'),
+    timeout_seconds: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe('Max seconds per item (default: 120)'),
+});
+export const AgenticMapParametersSchema = z.object({
+    input_path: z.string().describe('File path to JSONL input'),
+    max_attempts: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe('Max attempts per item (default: 3)'),
+    max_depth: z
+        .number()
+        .int()
+        .min(1)
+        .optional()
+        .describe('Maximum nesting depth for recursive agentic_map calls (default: 1). ' +
+        'Requires read_only=false. Capped at a hard server-side ceiling of 3. ' +
+        'Nested calls cannot increase the depth limit set by the root call.'),
+    output_path: z.string().describe('File path where JSONL output will be written'),
+    output_schema: z
+        .record(z.string(), z.any())
+        .describe('JSON Schema for sub-agent output validation'),
+    prompt: z.string().describe('Base instruction text for sub-agents'),
+    read_only: z
+        .boolean()
+        .optional()
+        .describe('If true, sub-agent write operations are disabled (default: true)'),
+    timeout_seconds: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe('Max seconds per item (default: 300)'),
+});
+// ── System Messages ──────────────────────────────────────────────────────────
+/**
+ * System message for LLM-Map: enforces stateless JSON-only output.
+ */
+export const LLM_MAP_SYSTEM_MESSAGE = [
+    'You are processing one item from a parallel LLM map.',
+    '',
+    'You must return exactly one JSON value as the entire response:',
+    '- No surrounding prose, explanations, or commentary.',
+    '- No markdown fences (no ```json blocks).',
+    '- No trailing text after the JSON.',
+    '',
+    'Your JSON output must validate against the schema provided in <map-details-json>.',
+    'If asked to retry due to an error, output corrected JSON only.',
+    '',
+    'No external tools exist and no actions can be taken beyond returning JSON text.',
+].join('\n');
+/**
+ * System message for Agentic-Map: allows tool access with JSON output.
+ */
+export function buildAgenticMapSystemMessage(readOnly) {
+    const lines = [
+        'You are operating on one item from a parallel agentic map.',
+        '',
+        'You must output exactly one JSON value as your final answer:',
+        '- No surrounding prose, explanations, or commentary.',
+        '- No markdown fences (no ```json blocks).',
+        '- No trailing text after the JSON.',
+        '',
+        'Your JSON output must validate against the schema provided in <map-details-json>.',
+        'If the system reports a JSON parsing or schema validation error, respond with corrected JSON only.',
+    ];
+    if (readOnly) {
+        lines.push('', 'Write operations (edit, write, bash) are disabled for this task.');
+    }
+    return lines.join('\n');
+}
+/**
+ * Build the recursive composition guidance block appended to sub-agent user messages
+ * when this depth level allows further nesting.
+ */
+export function buildRecursiveCompositionGuidance(currentDepth, maxDepth) {
+    const remaining = maxDepth - currentDepth;
+    return [
+        '<recursive-map-guidance>',
+        `You are at nesting depth ${currentDepth} (hard limit: ${maxDepth}).`,
+        `You may call agentic_map up to ${remaining} more level(s).`,
+        'Each nested call MUST use a distinct JSONL input_path.',
+        "Reusing an ancestor's input_path is a cycle and will fail immediately.",
+        '</recursive-map-guidance>',
+    ].join('\n');
+}
+// ── Shared Helpers ──────────────────────────────────────────────────────────
+/**
+ * Race a promise against an abort signal.
+ * Used across map services to enforce per-item timeouts on calls that
+ * don't natively accept AbortSignal (e.g., generateContent, executeOnSession).
+ */
+export function withTimeout(promise, signal) {
+    if (signal.aborted) {
+        return Promise.reject(new Error('Timed out'));
+    }
+    return new Promise((resolve, reject) => {
+        const onAbort = () => {
+            reject(new Error('Timed out'));
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+        promise.then((value) => {
+            signal.removeEventListener('abort', onAbort);
+            resolve(value);
+        }, (error) => {
+            signal.removeEventListener('abort', onAbort);
+            reject(error instanceof Error ? error : new Error(String(error)));
+        });
+    });
+}
+/**
+ * Stateless LLM call for map item processing.
+ * Shared by llm-map-service and llm-map-memory.
+ */
+export async function callLlm(generator, userMessage, taskId, abortSignal) {
+    if (abortSignal?.aborted) {
+        throw new Error('Aborted');
+    }
+    return generator.generateContent({
+        config: {
+            maxTokens: 4096,
+            temperature: 0,
+        },
+        contents: [
+            { content: userMessage, role: 'user' },
+        ],
+        model: 'default',
+        systemPrompt: LLM_MAP_SYSTEM_MESSAGE,
+        taskId: taskId ?? randomUUID(),
+    });
+}

package/dist/agent/infra/map/worker-pool.d.ts

@@ -0,0 +1,45 @@
+export interface MapProgress {
+    failed: number;
+    mapId: string;
+    running: number;
+    succeeded: number;
+    total: number;
+}
+export interface MapRunResult {
+    failed: number;
+    mapId: string;
+    succeeded: number;
+    summaryHandle?: string;
+    total: number;
+}
+export interface InMemoryMapRunResult extends MapRunResult {
+    /** Per-item results keyed by input index */
+    results: Map<number, unknown>;
+}
+export interface WorkerPoolOptions {
+    /** Abort signal to cancel all workers */
+    abortSignal?: AbortSignal;
+    /** Number of parallel workers */
+    concurrency: number;
+    /** Pre-loaded items from JSONL input */
+    items: unknown[];
+    /** Progress callback for streaming updates */
+    onProgress?: (progress: MapProgress) => void;
+    /** Function to process a single item. Must return the result or throw. */
+    processItem: (index: number, item: unknown) => Promise<unknown>;
+}
+/**
+ * In-memory parallel worker pool for map operations.
+ *
+ * N workers run in parallel via Promise.all(). Each worker claims items by
+ * incrementing a shared index counter (safe because JS is single-threaded
+ * for synchronous code — no cross-process races).
+ *
+ * Replaces the previous FileMapStore-backed implementation which used atomic
+ * file renames for item claiming. That pattern was ported from VoltCode's
+ * multi-process PostgreSQL architecture but is unnecessary for byterover-cli's
+ * single-process execution model.
+ *
+ * @returns Summary of the map run including a results Map (index → result)
+ */
+export declare function runMapWorkerPool(options: WorkerPoolOptions): Promise<InMemoryMapRunResult>;