@nodetool-ai/agents 0.7.0-rc.23 → 0.8.2

package/dist/utils/json-parser.js

@@ -1,17 +1,10 @@
 /**
  * Utility for extracting JSON from LLM text output.
  */
-/**
- * Attempt to extract a JSON value from a text string.
- *
- * Strategies (in order):
- * 1. Direct JSON.parse of the trimmed text.
- * 2. Extract from a fenced ```json code block.
- * 3. Find the first balanced { ... } substring.
- *
- * Returns null if no valid JSON can be extracted.
- */
 export function extractJSON(text) {
+    // Stryker disable next-line MethodExpression: JSON.parse already tolerates
+    // surrounding whitespace and strategy 3 scans via indexOf, so dropping trim()
+    // changes no observable result.
     const trimmed = text.trim();
     // Strategy 1: direct parse
     try {
@@ -21,9 +14,18 @@ export function extractJSON(text) {
         // continue
     }
     // Strategy 2: fenced code block
+    // Stryker disable next-line Regex: fence-regex variants are non-behavioral —
+    // strategy 3 (balanced braces) recovers any fenced object/array, and the
+    // captured group is .trim()'d before JSON.parse, so whitespace-class tweaks
+    // cannot change the parsed value.
     const fenceMatch = trimmed.match(/```(?:json)?\s*\n?([\s\S]*?)\n?```/);
+    // Stryker disable next-line ConditionalExpression: the `true` mutant only
+    // forces a JSON.parse on a missing/empty capture, which throws and is caught
+    // below — identical to skipping the fence path.
     if (fenceMatch?.[1]) {
         try {
+            // Stryker disable next-line MethodExpression: JSON.parse tolerates the
+            // surrounding whitespace, so trimming the captured group is cosmetic.
             return JSON.parse(fenceMatch[1].trim());
         }
         catch {
@@ -36,11 +38,16 @@ export function extractJSON(text) {
         ["[", "]"]
     ]) {
         const startIdx = trimmed.indexOf(open);
+        // Stryker disable next-line ConditionalExpression,UnaryOperator: when no
+        // opening bracket exists the scan below simply finds nothing, so skipping
+        // the `continue` only wastes a pass — the result is identical.
         if (startIdx === -1)
             continue;
         let depth = 0;
         let inString = false;
         let escape = false;
+        // Stryker disable next-line EqualityOperator: `< length`→`<= length` only
+        // visits one undefined trailing index that matches no branch (harmless).
         for (let i = startIdx; i < trimmed.length; i++) {
             const ch = trimmed[i];
             if (escape) {
@@ -61,6 +68,9 @@ export function extractJSON(text) {
                 depth++;
             if (ch === close) {
                 depth--;
+                // Stryker disable next-line ConditionalExpression: any close at depth>0
+                // yields an unbalanced prefix that never parses, so attempting a
+                // candidate there (the `true` mutant) is behaviorally equivalent.
                 if (depth === 0) {
                     const candidate = trimmed.slice(startIdx, i + 1);
                     try {
@@ -75,4 +85,129 @@ export function extractJSON(text) {
     }
     return null;
 }
+/**
+ * The largest reply {@link salvageTruncatedJSON} will try to repair.
+ *
+ * Repair walks candidate cut points and re-parses at each, so an unbounded
+ * input is quadratic. A judge reply that runs past this is not a truncated
+ * object; it is something else.
+ */
+const MAX_SALVAGE_CHARS = 200_000;
+/** How many cut points a single salvage may try before giving up. */
+const MAX_SALVAGE_ATTEMPTS = 300;
+/** Characters that can legally end a complete JSON value. */
+const VALUE_END = new Set([
+    "}",
+    "]",
+    '"',
+    "e", // true / false
+    "l", // null
+    "0",
+    "1",
+    "2",
+    "3",
+    "4",
+    "5",
+    "6",
+    "7",
+    "8",
+    "9"
+]);
+/**
+ * Recover the complete prefix of a JSON object that was cut off mid-write.
+ *
+ * A vision judge asked for `{"verdict": …, "defects": […]}` and stopped at its
+ * token ceiling three defects in. {@link extractJSON} returns null for that —
+ * every strategy needs a balanced document — so the caller reported "did not
+ * return parseable JSON" and threw away a verdict and two usable defects that
+ * were fully written.
+ *
+ * This drops the incomplete tail: it walks back from the end to the last point
+ * where a value had just closed, closes the brackets that were still open
+ * there, and parses that. Returns null when nothing parses — a reply that is
+ * not JSON at all stays an error, and a *complete* document is
+ * {@link extractJSON}'s job, so try that first.
+ */
+export function salvageTruncatedJSON(text) {
+    if (text.length > MAX_SALVAGE_CHARS)
+        return null;
+    const fence = text.match(/```(?:json)?\s*\n?([\s\S]*)$/);
+    const body = fence?.[1] ?? text;
+    const start = (() => {
+        const brace = body.indexOf("{");
+        const bracket = body.indexOf("[");
+        if (brace === -1)
+            return bracket;
+        if (bracket === -1)
+            return brace;
+        return Math.min(brace, bracket);
+    })();
+    if (start === -1)
+        return null;
+    // Forward pass: for every index, the bracket stack in force and whether the
+    // scanner is inside a string literal there.
+    const stacks = [];
+    const inString = [];
+    const stack = [];
+    let open = false;
+    let escape = false;
+    for (let i = start; i < body.length; i++) {
+        stacks.push([...stack]);
+        inString.push(open);
+        const ch = body[i];
+        if (escape) {
+            escape = false;
+            continue;
+        }
+        if (open) {
+            if (ch === "\\")
+                escape = true;
+            else if (ch === '"')
+                open = false;
+            continue;
+        }
+        if (ch === '"')
+            open = true;
+        else if (ch === "{")
+            stack.push("}");
+        else if (ch === "[")
+            stack.push("]");
+        else if (ch === "}" || ch === "]")
+            stack.pop();
+    }
+    stacks.push([...stack]);
+    inString.push(open);
+    let attempts = 0;
+    for (let cut = body.length; cut > start; cut--) {
+        const rel = cut - start;
+        if (inString[rel])
+            continue;
+        const prev = body[cut - 1];
+        if (!VALUE_END.has(prev))
+            continue;
+        const closers = stacks[rel];
+        if (closers.length === 0)
+            continue; // a balanced document is extractJSON's
+        if (++attempts > MAX_SALVAGE_ATTEMPTS)
+            break;
+        const candidate = body.slice(start, cut) + closers.slice().reverse().join("");
+        try {
+            return JSON.parse(candidate);
+        }
+        catch {
+            // keep walking back
+        }
+    }
+    return null;
+}
+/**
+ * {@link extractJSON}, falling back to {@link salvageTruncatedJSON}.
+ *
+ * For callers where a partial answer beats no answer — a critique whose
+ * defects list was cut short is still a critique. Never use it where a
+ * truncated document would be mistaken for a complete instruction.
+ */
+export function extractJSONAllowingTruncation(text) {
+    return extractJSON(text) ?? salvageTruncatedJSON(text);
+}
 //# sourceMappingURL=json-parser.js.map

package/dist/utils/json-parser.js.map

@@ -1 +1 @@
-{"version":3,"file":"json-parser.js","sourceRoot":"","sources":["../../src/utils/json-parser.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;;;GASG;AACH,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;IAE5B,2BAA2B;IAC3B,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC7B,CAAC;IAAC,MAAM,CAAC;QACP,WAAW;IACb,CAAC;IAED,gCAAgC;IAChC,MAAM,UAAU,GAAG,OAAO,CAAC,KAAK,CAAC,oCAAoC,CAAC,CAAC;IACvE,IAAI,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACpB,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;QAC1C,CAAC;QAAC,MAAM,CAAC;YACP,WAAW;QACb,CAAC;IACH,CAAC;IAED,0CAA0C;IAC1C,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI;QAC1B,CAAC,GAAG,EAAE,GAAG,CAAC;QACV,CAAC,GAAG,EAAE,GAAG,CAAC;KACF,EAAE,CAAC;QACX,MAAM,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACvC,IAAI,QAAQ,KAAK,CAAC,CAAC;YAAE,SAAS;QAC9B,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,IAAI,QAAQ,GAAG,KAAK,CAAC;QACrB,IAAI,MAAM,GAAG,KAAK,CAAC;QACnB,KAAK,IAAI,CAAC,GAAG,QAAQ,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YAC/C,MAAM,EAAE,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;YACtB,IAAI,MAAM,EAAE,CAAC;gBACX,MAAM,GAAG,KAAK,CAAC;gBACf,SAAS;YACX,CAAC;YACD,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC;gBAChB,MAAM,GAAG,IAAI,CAAC;gBACd,SAAS;YACX,CAAC;YACD,IAAI,EAAE,KAAK,GAAG,EAAE,CAAC;gBACf,QAAQ,GAAG,CAAC,QAAQ,CAAC;gBACrB,SAAS;YACX,CAAC;YACD,IAAI,QAAQ;gBAAE,SAAS;YACvB,IAAI,EAAE,KAAK,IAAI;gBAAE,KAAK,EAAE,CAAC;YACzB,IAAI,EAAE,KAAK,KAAK,EAAE,CAAC;gBACjB,KAAK,EAAE,CAAC;gBACR,IAAI,KAAK,KAAK,CAAC,EAAE,CAAC;oBAChB,MAAM,SAAS,GAAG,OAAO,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;oBACjD,IAAI,CAAC;wBACH,OAAO,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;oBAC/B,CAAC;oBAAC,MAAM,CAAC;wBACP,qBAAqB;oBACvB,CAAC;gBACH,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC"}
+{"version":3,"file":"json-parser.js","sourceRoot":"","sources":["../../src/utils/json-parser.ts"],"names":[],"mappings":"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"}

package/dist/utils/json-schema-validate.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Host-side JSON-schema validation for structured step results.
+ *
+ * A step declares an `outputSchema`; the model answers through `finish_step`.
+ * The provider-side tool schema is a hint at best — several backends drop
+ * `enum`, flatten unions, or ignore `additionalProperties` — so whether the
+ * answer really matches the contract has to be decided here. A verdict schema
+ * makes that concrete: "one of five actions, and `substitute` also carries
+ * outputs" is a discriminated union, and a validator that only checks the
+ * top-level type and required keys accepts a verdict the kernel will reject.
+ *
+ * Deliberately a subset of JSON Schema — the keywords a step contract uses,
+ * validated exactly, rather than the full specification validated loosely.
+ */
+export interface SchemaViolation {
+    /** JSON-path-ish location, e.g. `result.outputs.text`. */
+    path: string;
+    message: string;
+}
+type Schema = Record<string, unknown>;
+/**
+ * Validate `value` against `schema`. Returns every violation found, so one
+ * bounce back to the model can fix everything rather than one thing per round.
+ */
+export declare function validateAgainstSchema(value: unknown, schema: Schema, path?: string): SchemaViolation[];
+/** One-line rendering of violations, for a tool-result bounce. */
+export declare function formatViolations(violations: SchemaViolation[]): string;
+export {};
+//# sourceMappingURL=json-schema-validate.d.ts.map

package/dist/utils/json-schema-validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-schema-validate.d.ts","sourceRoot":"","sources":["../../src/utils/json-schema-validate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAUH,MAAM,WAAW,eAAe;IAC9B,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,KAAK,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AA4DtC;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,MAAM,EACd,IAAI,SAAW,GACd,eAAe,EAAE,CAInB;AAoLD,kEAAkE;AAClE,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,eAAe,EAAE,GAAG,MAAM,CAEtE"}

package/dist/utils/json-schema-validate.js

@@ -0,0 +1,228 @@
+/**
+ * Host-side JSON-schema validation for structured step results.
+ *
+ * A step declares an `outputSchema`; the model answers through `finish_step`.
+ * The provider-side tool schema is a hint at best — several backends drop
+ * `enum`, flatten unions, or ignore `additionalProperties` — so whether the
+ * answer really matches the contract has to be decided here. A verdict schema
+ * makes that concrete: "one of five actions, and `substitute` also carries
+ * outputs" is a discriminated union, and a validator that only checks the
+ * top-level type and required keys accepts a verdict the kernel will reject.
+ *
+ * Deliberately a subset of JSON Schema — the keywords a step contract uses,
+ * validated exactly, rather than the full specification validated loosely.
+ */
+import { isBoolean, isNumber, isObjectLike, isRecord, isString } from "./type-guards.js";
+const TYPE_NAMES = [
+    "string",
+    "number",
+    "integer",
+    "boolean",
+    "object",
+    "array",
+    "null"
+];
+/** A `type` keyword this validator knows. */
+function isTypeName(value) {
+    return (typeof value === "string" &&
+        TYPE_NAMES.includes(value));
+}
+function typeOf(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "array";
+    if (isNumber(value)) {
+        return Number.isInteger(value) ? "integer" : "number";
+    }
+    if (isString(value))
+        return "string";
+    if (isBoolean(value))
+        return "boolean";
+    return "object";
+}
+function matchesType(value, expected) {
+    const actual = typeOf(value);
+    if (expected === "number")
+        return actual === "number" || actual === "integer";
+    return actual === expected;
+}
+function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (typeof a !== typeof b || a === null || b === null)
+        return false;
+    if (Array.isArray(a) !== Array.isArray(b))
+        return false;
+    if (!isObjectLike(a))
+        return false;
+    const ao = a;
+    const bo = b;
+    const aKeys = Object.keys(ao);
+    if (aKeys.length !== Object.keys(bo).length)
+        return false;
+    return aKeys.every((key) => Object.hasOwn(bo, key) && deepEqual(ao[key], bo[key]));
+}
+function describe(value) {
+    const text = isString(value) ? value : JSON.stringify(value);
+    return text !== undefined && text.length > 60
+        ? `${text.slice(0, 60)}…`
+        : String(text);
+}
+/**
+ * Validate `value` against `schema`. Returns every violation found, so one
+ * bounce back to the model can fix everything rather than one thing per round.
+ */
+export function validateAgainstSchema(value, schema, path = "result") {
+    const out = [];
+    validate(value, schema, path, out);
+    return out;
+}
+function validate(value, schema, path, out) {
+    if (schema["const"] !== undefined && !deepEqual(value, schema["const"])) {
+        out.push({
+            path,
+            message: `must equal ${describe(schema["const"])}, got ${describe(value)}`
+        });
+        return;
+    }
+    const enumValues = schema["enum"];
+    if (Array.isArray(enumValues)) {
+        if (!enumValues.some((candidate) => deepEqual(value, candidate))) {
+            out.push({
+                path,
+                message: `must be one of ${enumValues.map((v) => describe(v)).join(", ")}, got ${describe(value)}`
+            });
+            return;
+        }
+    }
+    const declared = schema["type"];
+    const types = Array.isArray(declared)
+        ? declared.filter(isTypeName)
+        : isTypeName(declared)
+            ? [declared]
+            : [];
+    if (types.length > 0 && !types.some((t) => matchesType(value, t))) {
+        out.push({
+            path,
+            message: `expected ${types.join(" | ")}, got ${typeOf(value)}`
+        });
+        return;
+    }
+    if (typeOf(value) === "object") {
+        validateObject(value, schema, path, out);
+    }
+    if (Array.isArray(value))
+        validateArray(value, schema, path, out);
+    if (isNumber(value))
+        validateNumber(value, schema, path, out);
+    if (isString(value))
+        validateString(value, schema, path, out);
+    validateCombinators(value, schema, path, out);
+}
+function validateObject(value, schema, path, out) {
+    const required = schema["required"];
+    if (Array.isArray(required)) {
+        for (const key of required) {
+            // Object.hasOwn, not `in`: a required key named `toString` must be
+            // produced by the model, not inherited from the prototype chain.
+            if (isString(key) && !Object.hasOwn(value, key)) {
+                out.push({ path, message: `missing required property "${key}"` });
+            }
+        }
+    }
+    const properties = schema["properties"] ?? {};
+    for (const [key, sub] of Object.entries(properties)) {
+        if (!Object.hasOwn(value, key))
+            continue;
+        if (isObjectLike(sub)) {
+            validate(value[key], sub, `${path}.${key}`, out);
+        }
+    }
+    const additional = schema["additionalProperties"];
+    if (additional === false) {
+        for (const key of Object.keys(value)) {
+            if (!Object.hasOwn(properties, key)) {
+                out.push({ path, message: `unexpected property "${key}"` });
+            }
+        }
+    }
+    else if (isObjectLike(additional)) {
+        for (const [key, entry] of Object.entries(value)) {
+            if (Object.hasOwn(properties, key))
+                continue;
+            validate(entry, additional, `${path}.${key}`, out);
+        }
+    }
+}
+function validateArray(value, schema, path, out) {
+    const items = schema["items"];
+    if (isRecord(items)) {
+        value.forEach((entry, index) => validate(entry, items, `${path}[${index}]`, out));
+    }
+    const min = schema["minItems"];
+    if (isNumber(min) && value.length < min) {
+        out.push({ path, message: `expected at least ${min} items` });
+    }
+    const max = schema["maxItems"];
+    if (isNumber(max) && value.length > max) {
+        out.push({ path, message: `expected at most ${max} items` });
+    }
+}
+function validateNumber(value, schema, path, out) {
+    const min = schema["minimum"];
+    if (isNumber(min) && value < min) {
+        out.push({ path, message: `must be >= ${min}` });
+    }
+    const max = schema["maximum"];
+    if (isNumber(max) && value > max) {
+        out.push({ path, message: `must be <= ${max}` });
+    }
+}
+function validateString(value, schema, path, out) {
+    const min = schema["minLength"];
+    if (isNumber(min) && value.length < min) {
+        out.push({ path, message: `must be at least ${min} characters` });
+    }
+    const max = schema["maxLength"];
+    if (isNumber(max) && value.length > max) {
+        out.push({ path, message: `must be at most ${max} characters` });
+    }
+}
+function validateCombinators(value, schema, path, out) {
+    const allOf = schema["allOf"];
+    if (Array.isArray(allOf)) {
+        for (const sub of allOf) {
+            if (isObjectLike(sub)) {
+                validate(value, sub, path, out);
+            }
+        }
+    }
+    for (const keyword of ["anyOf", "oneOf"]) {
+        const branches = schema[keyword];
+        if (!Array.isArray(branches) || branches.length === 0)
+            continue;
+        // A branch that validates cleanly is the branch the model meant. Reporting
+        // every branch's failures would bury the real error under four irrelevant
+        // ones, so an all-fail reports the closest branch — fewest violations.
+        let closest = null;
+        for (const branch of branches) {
+            if (!isObjectLike(branch))
+                continue;
+            const errors = validateAgainstSchema(value, branch, path);
+            if (errors.length === 0) {
+                closest = null;
+                break;
+            }
+            if (closest === null || errors.length < closest.length)
+                closest = errors;
+        }
+        if (closest)
+            out.push(...closest);
+    }
+}
+/** One-line rendering of violations, for a tool-result bounce. */
+export function formatViolations(violations) {
+    return violations.map((v) => `${v.path}: ${v.message}`).join("; ");
+}
+//# sourceMappingURL=json-schema-validate.js.map

package/dist/utils/json-schema-validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-schema-validate.js","sourceRoot":"","sources":["../../src/utils/json-schema-validate.ts"],"names":[],"mappings":"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"}

package/dist/utils/link-abort.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Link an external cancellation signal to a locally-owned AbortController.
+ *
+ * Planners and executors own a private controller they fire for their own
+ * reasons (validation gave up, the step finished). Cancellation from outside —
+ * a user pressing Stop — has to reach that same controller, otherwise the
+ * provider call underneath it keeps running.
+ *
+ * Returns an unlink function; call it when the local controller's work is done
+ * so a long-lived external signal doesn't retain finished executors.
+ */
+export declare function linkAbort(local: AbortController, external?: AbortSignal): () => void;
+//# sourceMappingURL=link-abort.d.ts.map

package/dist/utils/link-abort.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"link-abort.d.ts","sourceRoot":"","sources":["../../src/utils/link-abort.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,eAAe,EACtB,QAAQ,CAAC,EAAE,WAAW,GACrB,MAAM,IAAI,CASZ"}

package/dist/utils/link-abort.js

@@ -0,0 +1,23 @@
+/**
+ * Link an external cancellation signal to a locally-owned AbortController.
+ *
+ * Planners and executors own a private controller they fire for their own
+ * reasons (validation gave up, the step finished). Cancellation from outside —
+ * a user pressing Stop — has to reach that same controller, otherwise the
+ * provider call underneath it keeps running.
+ *
+ * Returns an unlink function; call it when the local controller's work is done
+ * so a long-lived external signal doesn't retain finished executors.
+ */
+export function linkAbort(local, external) {
+    if (!external)
+        return () => { };
+    if (external.aborted) {
+        local.abort();
+        return () => { };
+    }
+    const onAbort = () => local.abort();
+    external.addEventListener("abort", onAbort, { once: true });
+    return () => external.removeEventListener("abort", onAbort);
+}
+//# sourceMappingURL=link-abort.js.map

package/dist/utils/link-abort.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"link-abort.js","sourceRoot":"","sources":["../../src/utils/link-abort.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,UAAU,SAAS,CACvB,KAAsB,EACtB,QAAsB;IAEtB,IAAI,CAAC,QAAQ;QAAE,OAAO,GAAG,EAAE,GAAE,CAAC,CAAC;IAC/B,IAAI,QAAQ,CAAC,OAAO,EAAE,CAAC;QACrB,KAAK,CAAC,KAAK,EAAE,CAAC;QACd,OAAO,GAAG,EAAE,GAAE,CAAC,CAAC;IAClB,CAAC;IACD,MAAM,OAAO,GAAG,GAAG,EAAE,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACpC,QAAQ,CAAC,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5D,OAAO,GAAG,EAAE,CAAC,QAAQ,CAAC,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;AAC9D,CAAC"}

package/dist/utils/merge-generators.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Bounded merge of async generators.
+ *
+ * Interleaves the output of several generators into one stream. `concurrency`
+ * caps how many run at once — the executors fan out over LLM-driven work, and
+ * an uncapped fan-out over a 200-item discover list opens 200 provider
+ * conversations simultaneously. Script mode has had a semaphore since it
+ * shipped; this is the same bound for the task-plan modes.
+ *
+ * A number bounds *this* merge and nothing else, so nested fan-outs multiply:
+ * eight tasks, each dispatching eight steps, each fanning out over eight items
+ * is 512 provider conversations under a `concurrency` of 8. A {@link Semaphore}
+ * is the run's own permit pool, so passing one bounds every merge that shares
+ * it together. Both may be given: the number caps this merge, the pool caps the
+ * run.
+ *
+ * Generators are lazy: one that has not been started yet has issued no provider
+ * call, so holding it back costs nothing.
+ *
+ * {@link createDynamicMerge} has an open end: generators may be added while the
+ * stream is being consumed, which is what lets the DAG scheduler start a node
+ * the moment its last dependency settles instead of at the end of a barrier
+ * round.
+ */
+import type { Semaphore } from "@nodetool-ai/runtime";
+export interface MergeOptions {
+    /** Maximum generators consumed at once. Defaults to unbounded. */
+    concurrency?: number;
+    /**
+     * Run-level permit pool. A generator holds one permit for as long as it is
+     * consumed, so several merges sharing a pool share one bound rather than
+     * each getting `concurrency` of their own.
+     */
+    semaphore?: Semaphore;
+}
+export interface DynamicMergeOptions extends MergeOptions {
+    /**
+     * Ends the stream when it fires. Every started generator is returned and its
+     * producer task awaited, the same as when a consumer breaks out early.
+     */
+    signal?: AbortSignal;
+}
+export interface DynamicMerge<T> {
+    /**
+     * Queue a generator. It starts as soon as a slot and a permit are free, and
+     * is ignored once the stream has ended.
+     */
+    add(generator: AsyncGenerator<T>): void;
+    /** No more generators will be added; the stream ends once the rest drain. */
+    close(): void;
+    /**
+     * The merged stream. Call once — a second call would consume the same queue.
+     * Nothing starts until it is iterated.
+     */
+    stream(): AsyncGenerator<T>;
+}
+export declare function createDynamicMerge<T>(options?: DynamicMergeOptions): DynamicMerge<T>;
+//# sourceMappingURL=merge-generators.d.ts.map

package/dist/utils/merge-generators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge-generators.d.ts","sourceRoot":"","sources":["../../src/utils/merge-generators.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAW,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAE/D,MAAM,WAAW,YAAY;IAC3B,kEAAkE;IAClE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AAED,MAAM,WAAW,mBAAoB,SAAQ,YAAY;IACvD;;;OAGG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B;;;OAGG;IACH,GAAG,CAAC,SAAS,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IACxC,6EAA6E;IAC7E,KAAK,IAAI,IAAI,CAAC;IACd;;;OAGG;IACH,MAAM,IAAI,cAAc,CAAC,CAAC,CAAC,CAAC;CAC7B;AAED,wBAAgB,kBAAkB,CAAC,CAAC,EAClC,OAAO,GAAE,mBAAwB,GAChC,YAAY,CAAC,CAAC,CAAC,CA8HjB"}