@adhisang/minecraft-modding-mcp 3.2.0 → 4.1.0

package/dist/entry-tools/analyze-symbol-service.d.ts

@@ -6,7 +6,7 @@ export declare const analyzeSymbolShape: {
         kind: z.ZodEnum<["class", "method", "field", "symbol"]>;
         name: z.ZodString;
         owner: z.ZodOptional<z.ZodString>;
-        descriptor: z.ZodOptional<z.ZodString>;
+        descriptor: z.ZodEffects<z.ZodOptional<z.ZodString>, string | undefined, string | undefined>;
     }, "strip", z.ZodTypeAny, {
         name: string;
         kind: "symbol" | "class" | "field" | "method";
@@ -37,7 +37,7 @@ export declare const analyzeSymbolSchema: z.ZodEffects<z.ZodObject<{
         kind: z.ZodEnum<["class", "method", "field", "symbol"]>;
         name: z.ZodString;
         owner: z.ZodOptional<z.ZodString>;
-        descriptor: z.ZodOptional<z.ZodString>;
+        descriptor: z.ZodEffects<z.ZodOptional<z.ZodString>, string | undefined, string | undefined>;
     }, "strip", z.ZodTypeAny, {
         name: string;
         kind: "symbol" | "class" | "field" | "method";
@@ -72,11 +72,11 @@ export declare const analyzeSymbolSchema: z.ZodEffects<z.ZodObject<{
     };
     signatureMode: "exact" | "name-only";
     maxCandidates: number;
-    projectPath?: string | undefined;
     version?: string | undefined;
-    sourceMapping?: "intermediary" | "mojang" | "yarn" | "obfuscated" | undefined;
-    targetMapping?: "intermediary" | "mojang" | "yarn" | "obfuscated" | undefined;
-    classNameMapping?: "intermediary" | "mojang" | "yarn" | "obfuscated" | undefined;
+    projectPath?: string | undefined;
+    sourceMapping?: "obfuscated" | "mojang" | "intermediary" | "yarn" | undefined;
+    targetMapping?: "obfuscated" | "mojang" | "intermediary" | "yarn" | undefined;
+    classNameMapping?: "obfuscated" | "mojang" | "intermediary" | "yarn" | undefined;
     detail?: "full" | "summary" | "standard" | undefined;
     include?: string[] | undefined;
     includeKinds?: ("class" | "field" | "method")[] | undefined;
@@ -89,11 +89,11 @@ export declare const analyzeSymbolSchema: z.ZodEffects<z.ZodObject<{
         descriptor?: string | undefined;
         owner?: string | undefined;
     };
-    projectPath?: string | undefined;
     version?: string | undefined;
-    sourceMapping?: "intermediary" | "mojang" | "yarn" | "obfuscated" | undefined;
-    targetMapping?: "intermediary" | "mojang" | "yarn" | "obfuscated" | undefined;
-    classNameMapping?: "intermediary" | "mojang" | "yarn" | "obfuscated" | undefined;
+    projectPath?: string | undefined;
+    sourceMapping?: "obfuscated" | "mojang" | "intermediary" | "yarn" | undefined;
+    targetMapping?: "obfuscated" | "mojang" | "intermediary" | "yarn" | undefined;
+    classNameMapping?: "obfuscated" | "mojang" | "intermediary" | "yarn" | undefined;
     nameMode?: "auto" | "fqcn" | undefined;
     detail?: "full" | "summary" | "standard" | undefined;
     include?: string[] | undefined;
@@ -112,11 +112,11 @@ export declare const analyzeSymbolSchema: z.ZodEffects<z.ZodObject<{
     };
     signatureMode: "exact" | "name-only";
     maxCandidates: number;
-    projectPath?: string | undefined;
     version?: string | undefined;
-    sourceMapping?: "intermediary" | "mojang" | "yarn" | "obfuscated" | undefined;
-    targetMapping?: "intermediary" | "mojang" | "yarn" | "obfuscated" | undefined;
-    classNameMapping?: "intermediary" | "mojang" | "yarn" | "obfuscated" | undefined;
+    projectPath?: string | undefined;
+    sourceMapping?: "obfuscated" | "mojang" | "intermediary" | "yarn" | undefined;
+    targetMapping?: "obfuscated" | "mojang" | "intermediary" | "yarn" | undefined;
+    classNameMapping?: "obfuscated" | "mojang" | "intermediary" | "yarn" | undefined;
     detail?: "full" | "summary" | "standard" | undefined;
     include?: string[] | undefined;
     includeKinds?: ("class" | "field" | "method")[] | undefined;
@@ -129,11 +129,11 @@ export declare const analyzeSymbolSchema: z.ZodEffects<z.ZodObject<{
         descriptor?: string | undefined;
         owner?: string | undefined;
     };
-    projectPath?: string | undefined;
     version?: string | undefined;
-    sourceMapping?: "intermediary" | "mojang" | "yarn" | "obfuscated" | undefined;
-    targetMapping?: "intermediary" | "mojang" | "yarn" | "obfuscated" | undefined;
-    classNameMapping?: "intermediary" | "mojang" | "yarn" | "obfuscated" | undefined;
+    projectPath?: string | undefined;
+    sourceMapping?: "obfuscated" | "mojang" | "intermediary" | "yarn" | undefined;
+    targetMapping?: "obfuscated" | "mojang" | "intermediary" | "yarn" | undefined;
+    classNameMapping?: "obfuscated" | "mojang" | "intermediary" | "yarn" | undefined;
     nameMode?: "auto" | "fqcn" | undefined;
     detail?: "full" | "summary" | "standard" | undefined;
     include?: string[] | undefined;

package/dist/entry-tools/analyze-symbol-service.js

@@ -4,6 +4,17 @@ import { buildIncludeSchema, detailSchema, positiveIntSchema } from "./entry-too
 import { buildEntryToolResult, createSummarySubject } from "./response-contract.js";
 import { resolveDetail, resolveInclude } from "./request-normalizers.js";
 const nonEmptyString = z.string().trim().min(1);
+// Descriptor field that treats empty/whitespace strings as omitted so callers can pass
+// `descriptor: ""` interchangeably with omitting the field when signatureMode="name-only".
+const optionalDescriptorString = z
+    .string()
+    .optional()
+    .transform((value) => {
+    if (value === undefined)
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed.length === 0 ? undefined : trimmed;
+});
 const INCLUDE_GROUPS = ["warnings", "candidates", "matrix", "workspace", "timings"];
 const TASKS = ["exists", "map", "exact-map", "lifecycle", "workspace", "api-overview"];
 export const analyzeSymbolShape = {
@@ -12,7 +23,7 @@ export const analyzeSymbolShape = {
         kind: z.enum(["class", "method", "field", "symbol"]),
         name: nonEmptyString,
         owner: nonEmptyString.optional(),
-        descriptor: nonEmptyString.optional()
+        descriptor: optionalDescriptorString
     }),
     version: nonEmptyString.optional(),
     sourceMapping: z.enum(["obfuscated", "mojang", "intermediary", "yarn"]).optional(),
@@ -23,7 +34,7 @@ export const analyzeSymbolShape = {
     nameMode: z.enum(["fqcn", "auto"]).default("fqcn"),
     includeKinds: z.array(z.enum(["class", "field", "method"])).optional(),
     maxRows: positiveIntSchema.optional(),
-    maxCandidates: positiveIntSchema.default(200),
+    maxCandidates: positiveIntSchema.default(5),
     detail: detailSchema.optional(),
     include: buildIncludeSchema(INCLUDE_GROUPS)
 };

package/dist/entry-tools/batch-class-members-service.d.ts

@@ -0,0 +1,34 @@
+import type { GetClassMembersInput, GetClassMembersOutput, ResolveArtifactInput, ResolveArtifactOutput } from "../source-service.js";
+import type { ArtifactScope, MappingSourcePriority, ResolveArtifactTargetInput, SourceMapping } from "../types.js";
+import { type BatchOutput } from "./batch-runner.js";
+export type BatchClassMembersDeps = {
+    resolveArtifact: (input: ResolveArtifactInput) => Promise<ResolveArtifactOutput>;
+    getClassMembers: (input: GetClassMembersInput) => Promise<GetClassMembersOutput>;
+};
+export type BatchClassMembersEntry = {
+    className: string;
+    access?: "public" | "all";
+    includeSynthetic?: boolean;
+    includeInherited?: boolean;
+    memberPattern?: string;
+    maxMembers?: number;
+};
+export type BatchClassMembersInput = {
+    target: ResolveArtifactTargetInput;
+    mapping?: SourceMapping;
+    sourcePriority?: MappingSourcePriority;
+    allowDecompile?: boolean;
+    projectPath?: string;
+    scope?: ArtifactScope;
+    preferProjectVersion?: boolean;
+    strictVersion?: boolean;
+    concurrency?: number;
+    failFast?: boolean;
+    compact?: boolean;
+    entries: readonly BatchClassMembersEntry[];
+};
+export declare class BatchClassMembersService {
+    private readonly deps;
+    constructor(deps: BatchClassMembersDeps);
+    execute(input: BatchClassMembersInput): Promise<BatchOutput<Record<string, unknown>>>;
+}

package/dist/entry-tools/batch-class-members-service.js

@@ -0,0 +1,97 @@
+import { buildSuggestedCall } from "../build-suggested-call.js";
+import { compactResponse, compactMembersResponse, TOOL_PRESERVE_PAYLOAD_KEYS } from "../response-utils.js";
+import { runBatch, splitEntryWarnings } from "./batch-runner.js";
+export class BatchClassMembersService {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async execute(input) {
+        const concurrency = input.concurrency ?? 4;
+        const failFast = input.failFast ?? false;
+        const compact = input.compact ?? true;
+        return runBatch({
+            entries: input.entries,
+            concurrency,
+            failFast,
+            resolveSharedArtifact: async () => {
+                const resolved = await this.deps.resolveArtifact({
+                    target: input.target,
+                    mapping: input.mapping,
+                    sourcePriority: input.sourcePriority,
+                    allowDecompile: input.allowDecompile,
+                    projectPath: input.projectPath,
+                    scope: input.scope,
+                    preferProjectVersion: input.preferProjectVersion,
+                    strictVersion: input.strictVersion
+                });
+                return {
+                    artifactId: resolved.artifactId,
+                    provenance: resolved.provenance,
+                    ...(Array.isArray(resolved.warnings) && resolved.warnings.length > 0
+                        ? { warnings: [...resolved.warnings] }
+                        : {})
+                };
+            },
+            artifactSummary: (artifact) => ({
+                sharedArtifactId: artifact.artifactId,
+                ...(artifact.provenance ? { sharedArtifactProvenance: artifact.provenance } : {}),
+                ...(artifact.warnings && artifact.warnings.length > 0
+                    ? { sharedArtifactWarnings: artifact.warnings }
+                    : {})
+            }),
+            perEntry: async (entry, _index, sharedArtifact) => {
+                if (!sharedArtifact) {
+                    throw new Error("shared artifact not resolved");
+                }
+                const raw = (await this.deps.getClassMembers({
+                    artifactId: sharedArtifact.artifactId,
+                    className: entry.className,
+                    access: entry.access,
+                    includeSynthetic: entry.includeSynthetic,
+                    includeInherited: entry.includeInherited,
+                    memberPattern: entry.memberPattern,
+                    maxMembers: entry.maxMembers,
+                    mapping: input.mapping,
+                    sourcePriority: input.sourcePriority,
+                    allowDecompile: input.allowDecompile,
+                    projectPath: input.projectPath,
+                    scope: input.scope,
+                    preferProjectVersion: input.preferProjectVersion,
+                    strictVersion: input.strictVersion
+                }));
+                const { result, warnings } = splitEntryWarnings(raw);
+                const projected = compact
+                    ? compactResponse(compactMembersResponse(result), TOOL_PRESERVE_PAYLOAD_KEYS["get-class-members"])
+                    : result;
+                return { result: projected, warnings };
+            },
+            buildErrorSuggestedCall: (entry, sharedArtifact) => {
+                if (!sharedArtifact)
+                    return undefined;
+                const params = {
+                    target: { type: "artifact", artifactId: sharedArtifact.artifactId },
+                    className: entry.className
+                };
+                if (entry.access !== undefined)
+                    params.access = entry.access;
+                if (entry.includeSynthetic !== undefined)
+                    params.includeSynthetic = entry.includeSynthetic;
+                if (entry.includeInherited !== undefined)
+                    params.includeInherited = entry.includeInherited;
+                if (entry.memberPattern !== undefined)
+                    params.memberPattern = entry.memberPattern;
+                if (entry.maxMembers !== undefined)
+                    params.maxMembers = entry.maxMembers;
+                if (input.mapping !== undefined)
+                    params.mapping = input.mapping;
+                const { suggestedCall } = buildSuggestedCall({
+                    tool: "get-class-members",
+                    params
+                });
+                return suggestedCall;
+            }
+        });
+    }
+}
+//# sourceMappingURL=batch-class-members-service.js.map

package/dist/entry-tools/batch-class-source-service.d.ts

@@ -0,0 +1,37 @@
+import type { GetClassSourceInput, GetClassSourceOutput, ResolveArtifactInput, ResolveArtifactOutput } from "../source-service.js";
+import type { ArtifactScope, MappingSourcePriority, ResolveArtifactTargetInput, SourceMapping } from "../types.js";
+import { type BatchOutput } from "./batch-runner.js";
+type SourceMode = "metadata" | "snippet" | "full";
+export type BatchClassSourceEntry = {
+    className: string;
+    mode?: SourceMode;
+    startLine?: number;
+    endLine?: number;
+    maxLines?: number;
+    maxChars?: number;
+    outputFile?: string;
+};
+export type BatchClassSourceInput = {
+    target: ResolveArtifactTargetInput;
+    mapping?: SourceMapping;
+    sourcePriority?: MappingSourcePriority;
+    allowDecompile?: boolean;
+    projectPath?: string;
+    scope?: ArtifactScope;
+    preferProjectVersion?: boolean;
+    strictVersion?: boolean;
+    concurrency?: number;
+    failFast?: boolean;
+    compact?: boolean;
+    entries: readonly BatchClassSourceEntry[];
+};
+export type BatchClassSourceDeps = {
+    resolveArtifact: (input: ResolveArtifactInput) => Promise<ResolveArtifactOutput>;
+    getClassSource: (input: GetClassSourceInput) => Promise<GetClassSourceOutput>;
+};
+export declare class BatchClassSourceService {
+    private readonly deps;
+    constructor(deps: BatchClassSourceDeps);
+    execute(input: BatchClassSourceInput): Promise<BatchOutput<Record<string, unknown>>>;
+}
+export {};

package/dist/entry-tools/batch-class-source-service.js

@@ -0,0 +1,100 @@
+import { buildSuggestedCall } from "../build-suggested-call.js";
+import { compactResponse, compactSourceResponse, TOOL_PRESERVE_PAYLOAD_KEYS } from "../response-utils.js";
+import { runBatch, splitEntryWarnings } from "./batch-runner.js";
+export class BatchClassSourceService {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async execute(input) {
+        const concurrency = input.concurrency ?? 4;
+        const failFast = input.failFast ?? false;
+        const compact = input.compact ?? true;
+        return runBatch({
+            entries: input.entries,
+            concurrency,
+            failFast,
+            resolveSharedArtifact: async () => {
+                const resolved = await this.deps.resolveArtifact({
+                    target: input.target,
+                    mapping: input.mapping,
+                    sourcePriority: input.sourcePriority,
+                    allowDecompile: input.allowDecompile,
+                    projectPath: input.projectPath,
+                    scope: input.scope,
+                    preferProjectVersion: input.preferProjectVersion,
+                    strictVersion: input.strictVersion
+                });
+                return {
+                    artifactId: resolved.artifactId,
+                    provenance: resolved.provenance,
+                    ...(Array.isArray(resolved.warnings) && resolved.warnings.length > 0
+                        ? { warnings: [...resolved.warnings] }
+                        : {})
+                };
+            },
+            artifactSummary: (artifact) => ({
+                sharedArtifactId: artifact.artifactId,
+                ...(artifact.provenance ? { sharedArtifactProvenance: artifact.provenance } : {}),
+                ...(artifact.warnings && artifact.warnings.length > 0
+                    ? { sharedArtifactWarnings: artifact.warnings }
+                    : {})
+            }),
+            perEntry: async (entry, _index, sharedArtifact) => {
+                if (!sharedArtifact) {
+                    throw new Error("shared artifact not resolved");
+                }
+                const raw = (await this.deps.getClassSource({
+                    artifactId: sharedArtifact.artifactId,
+                    className: entry.className,
+                    mode: entry.mode,
+                    startLine: entry.startLine,
+                    endLine: entry.endLine,
+                    maxLines: entry.maxLines,
+                    maxChars: entry.maxChars,
+                    outputFile: entry.outputFile,
+                    mapping: input.mapping,
+                    sourcePriority: input.sourcePriority,
+                    allowDecompile: input.allowDecompile,
+                    projectPath: input.projectPath,
+                    scope: input.scope,
+                    preferProjectVersion: input.preferProjectVersion,
+                    strictVersion: input.strictVersion
+                }));
+                const { result, warnings } = splitEntryWarnings(raw);
+                const projected = compact
+                    ? compactResponse(compactSourceResponse(result), TOOL_PRESERVE_PAYLOAD_KEYS["get-class-source"])
+                    : result;
+                return { result: projected, warnings };
+            },
+            buildErrorSuggestedCall: (entry, sharedArtifact) => {
+                if (!sharedArtifact)
+                    return undefined;
+                const params = {
+                    target: { type: "artifact", artifactId: sharedArtifact.artifactId },
+                    className: entry.className
+                };
+                if (entry.mode !== undefined)
+                    params.mode = entry.mode;
+                if (entry.startLine !== undefined)
+                    params.startLine = entry.startLine;
+                if (entry.endLine !== undefined)
+                    params.endLine = entry.endLine;
+                if (entry.maxLines !== undefined)
+                    params.maxLines = entry.maxLines;
+                if (entry.maxChars !== undefined)
+                    params.maxChars = entry.maxChars;
+                if (entry.outputFile !== undefined)
+                    params.outputFile = entry.outputFile;
+                if (input.mapping !== undefined)
+                    params.mapping = input.mapping;
+                const { suggestedCall } = buildSuggestedCall({
+                    tool: "get-class-source",
+                    params
+                });
+                return suggestedCall;
+            }
+        });
+    }
+}
+//# sourceMappingURL=batch-class-source-service.js.map

package/dist/entry-tools/batch-mappings-service.d.ts

@@ -0,0 +1,36 @@
+import type { FindMappingInput, FindMappingOutput } from "../source-service.js";
+import type { MappingSourcePriority, SourceMapping } from "../types.js";
+export type BatchMappingsDeps = {
+    findMapping: (input: FindMappingInput) => Promise<FindMappingOutput>;
+};
+import { type BatchOutput } from "./batch-runner.js";
+type SymbolKind = "class" | "field" | "method";
+export type BatchMappingsEntry = {
+    kind: SymbolKind;
+    name: string;
+    owner?: string;
+    descriptor?: string;
+    sourceMapping: SourceMapping;
+    targetMapping: SourceMapping;
+    signatureMode?: "exact" | "name-only";
+    disambiguation?: {
+        ownerHint?: string;
+        descriptorHint?: string;
+    };
+    maxCandidates?: number;
+};
+export type BatchMappingsInput = {
+    version: string;
+    sourcePriority?: MappingSourcePriority;
+    projectPath?: string;
+    concurrency?: number;
+    failFast?: boolean;
+    compact?: boolean;
+    entries: readonly BatchMappingsEntry[];
+};
+export declare class BatchMappingsService {
+    private readonly deps;
+    constructor(deps: BatchMappingsDeps);
+    execute(input: BatchMappingsInput): Promise<BatchOutput<Record<string, unknown>>>;
+}
+export {};

package/dist/entry-tools/batch-mappings-service.js

@@ -0,0 +1,66 @@
+import { buildSuggestedCall } from "../build-suggested-call.js";
+import { compactResponse, compactMappingResponse } from "../response-utils.js";
+import { runBatch, splitEntryWarnings } from "./batch-runner.js";
+export class BatchMappingsService {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async execute(input) {
+        const concurrency = input.concurrency ?? 4;
+        const failFast = input.failFast ?? false;
+        const compact = input.compact ?? true;
+        return runBatch({
+            entries: input.entries,
+            concurrency,
+            failFast,
+            resolveSharedArtifact: async () => undefined,
+            perEntry: async (entry, _index) => {
+                const raw = (await this.deps.findMapping({
+                    version: input.version,
+                    kind: entry.kind,
+                    name: entry.name,
+                    owner: entry.owner,
+                    descriptor: entry.descriptor,
+                    sourceMapping: entry.sourceMapping,
+                    targetMapping: entry.targetMapping,
+                    sourcePriority: input.sourcePriority,
+                    projectPath: input.projectPath,
+                    signatureMode: entry.signatureMode,
+                    disambiguation: entry.disambiguation,
+                    maxCandidates: entry.maxCandidates
+                }));
+                const { result, warnings } = splitEntryWarnings(raw);
+                const projected = compact
+                    ? compactResponse(compactMappingResponse(result))
+                    : result;
+                return { result: projected, warnings };
+            },
+            buildErrorSuggestedCall: (entry) => {
+                const params = {
+                    version: input.version,
+                    kind: entry.kind,
+                    name: entry.name,
+                    sourceMapping: entry.sourceMapping,
+                    targetMapping: entry.targetMapping
+                };
+                if (entry.owner !== undefined)
+                    params.owner = entry.owner;
+                if (entry.descriptor !== undefined)
+                    params.descriptor = entry.descriptor;
+                if (entry.signatureMode !== undefined)
+                    params.signatureMode = entry.signatureMode;
+                if (entry.disambiguation !== undefined)
+                    params.disambiguation = entry.disambiguation;
+                if (entry.maxCandidates !== undefined)
+                    params.maxCandidates = entry.maxCandidates;
+                const { suggestedCall } = buildSuggestedCall({
+                    tool: "find-mapping",
+                    params
+                });
+                return suggestedCall;
+            }
+        });
+    }
+}
+//# sourceMappingURL=batch-mappings-service.js.map

package/dist/entry-tools/batch-runner.d.ts

@@ -0,0 +1,72 @@
+import { type ProblemDetails, type SuggestedCall } from "../error-mapping.js";
+export declare const BATCH_TOOLS_OFF: boolean;
+export type BatchEntryOk<TResult> = {
+    index: number;
+    status: "ok";
+    result: TResult;
+    warnings: string[];
+    durationMs: number;
+};
+export type BatchEntryError = {
+    index: number;
+    status: "error";
+    error: ProblemDetails;
+    warnings: string[];
+    durationMs: number;
+};
+export type BatchEntryResult<TResult> = BatchEntryOk<TResult> | BatchEntryError;
+export type BatchSummary = {
+    total: number;
+    ok: number;
+    error: number;
+    sharedArtifactId?: string;
+    sharedArtifactProvenance?: Record<string, unknown>;
+    /** Warnings from the one-shot shared `resolveArtifact` call (version
+     * approximation, mapping fallback, source coverage gaps, workspace /
+     * dependency resolution caveats). Per-entry dispatch is by `artifactId`
+     * and never re-runs resolution, so these warnings reach the caller only
+     * via this field. Omitted when the resolution emitted none. */
+    sharedArtifactWarnings?: string[];
+};
+export type BatchOutput<TResult> = {
+    results: BatchEntryResult<TResult>[];
+    summary: BatchSummary;
+};
+export type BatchRunOptions<TEntry, TResult, TArtifact> = {
+    entries: readonly TEntry[];
+    concurrency: number;
+    failFast: boolean;
+    /** Resolve the shared artifact once. May return undefined for batch tools that
+     * do not need a shared artifact (e.g. `batch-mappings`, where each entry is
+     * mapping-graph-only and does not depend on the artifact). Throws to abort the
+     * batch entirely with a top-level error envelope (handled by `runTool`). */
+    resolveSharedArtifact: () => Promise<TArtifact | undefined>;
+    /** Summary metadata derived from the resolved shared artifact. */
+    artifactSummary?: (artifact: TArtifact) => {
+        sharedArtifactId?: string;
+        sharedArtifactProvenance?: Record<string, unknown>;
+        sharedArtifactWarnings?: string[];
+    };
+    /** Per-entry handler. Returns `{ result, warnings }` on success. Errors thrown
+     * here are caught and converted to a per-entry ProblemDetails — the mapper
+     * itself never throws into `mapWithConcurrencyLimit`. */
+    perEntry: (entry: TEntry, index: number, sharedArtifact: TArtifact | undefined) => Promise<{
+        result: TResult;
+        warnings?: string[];
+    }>;
+    /** Synthesize the per-entry retry suggestedCall (proposing the matching single
+     * tool). Already validated through `buildSuggestedCall` by the caller; pass
+     * `undefined` when the suggestedCall could not be synthesized for this entry. */
+    buildErrorSuggestedCall: (entry: TEntry, sharedArtifact: TArtifact | undefined, error: unknown) => SuggestedCall | undefined;
+    /** Generate a fresh request-instance id per entry — defaults to the same
+     * scheme `runTool` uses (`<base36-time>-<base36-rand>`). Per-entry uniqueness
+     * is required so callers can correlate failed entries individually. */
+    buildEntryInstance?: (index: number) => string;
+};
+export declare function runBatch<TEntry, TResult, TArtifact>(opts: BatchRunOptions<TEntry, TResult, TArtifact>): Promise<BatchOutput<TResult>>;
+/** Lift `warnings: string[]` off a service result onto the per-entry batch
+ * envelope, mirroring `runTool`'s `splitWarnings` for single-tool calls. */
+export declare function splitEntryWarnings<T extends Record<string, unknown>>(raw: T): {
+    result: Omit<T, "warnings">;
+    warnings: string[];
+};

package/dist/entry-tools/batch-runner.js

@@ -0,0 +1,90 @@
+import { mapWithConcurrencyLimit } from "../concurrency.js";
+import { buildBatchAbortedProblem, errorToBatchEntryProblem } from "../error-mapping.js";
+export const BATCH_TOOLS_OFF = process.env.BATCH_TOOLS_OFF === "1";
+function defaultEntryInstance(index) {
+    return `${Date.now().toString(36)}-${index}-${Math.random().toString(36).slice(2, 10)}`;
+}
+export async function runBatch(opts) {
+    const sharedArtifact = await opts.resolveSharedArtifact();
+    const artifactSummary = sharedArtifact !== undefined && opts.artifactSummary
+        ? opts.artifactSummary(sharedArtifact)
+        : {};
+    let abort = false;
+    const buildInstance = opts.buildEntryInstance ?? defaultEntryInstance;
+    const results = await mapWithConcurrencyLimit(opts.entries, opts.concurrency, async (entry, index) => {
+        const startedAt = Date.now();
+        if (abort) {
+            return {
+                index,
+                status: "error",
+                error: buildBatchAbortedProblem(buildInstance(index)),
+                warnings: [],
+                durationMs: Date.now() - startedAt
+            };
+        }
+        try {
+            const { result, warnings } = await opts.perEntry(entry, index, sharedArtifact);
+            return {
+                index,
+                status: "ok",
+                result,
+                warnings: warnings ?? [],
+                durationMs: Date.now() - startedAt
+            };
+        }
+        catch (caught) {
+            const suggestedCall = opts.buildErrorSuggestedCall(entry, sharedArtifact, caught);
+            const problem = errorToBatchEntryProblem(caught, buildInstance(index), suggestedCall ? { suggestedCall } : undefined);
+            if (opts.failFast) {
+                abort = true;
+            }
+            return {
+                index,
+                status: "error",
+                error: problem,
+                warnings: [],
+                durationMs: Date.now() - startedAt
+            };
+        }
+    });
+    let okCount = 0;
+    let errorCount = 0;
+    for (const entry of results) {
+        if (entry.status === "ok")
+            okCount += 1;
+        else
+            errorCount += 1;
+    }
+    return {
+        results,
+        summary: {
+            total: results.length,
+            ok: okCount,
+            error: errorCount,
+            ...(artifactSummary.sharedArtifactId !== undefined
+                ? { sharedArtifactId: artifactSummary.sharedArtifactId }
+                : {}),
+            ...(artifactSummary.sharedArtifactProvenance !== undefined
+                ? { sharedArtifactProvenance: artifactSummary.sharedArtifactProvenance }
+                : {}),
+            ...(artifactSummary.sharedArtifactWarnings !== undefined &&
+                artifactSummary.sharedArtifactWarnings.length > 0
+                ? { sharedArtifactWarnings: artifactSummary.sharedArtifactWarnings }
+                : {})
+        }
+    };
+}
+/** Lift `warnings: string[]` off a service result onto the per-entry batch
+ * envelope, mirroring `runTool`'s `splitWarnings` for single-tool calls. */
+export function splitEntryWarnings(raw) {
+    const { warnings, ...rest } = raw;
+    const list = [];
+    if (Array.isArray(warnings)) {
+        for (const w of warnings) {
+            if (typeof w === "string")
+                list.push(w);
+        }
+    }
+    return { result: rest, warnings: list };
+}
+//# sourceMappingURL=batch-runner.js.map