@nodetool-ai/agents 0.7.0-rc.22 → 0.8.1

package/dist/tools/subtask-fields.js

@@ -0,0 +1,11 @@
+/**
+ * Reserved field names shared between {@link StepExecutor} and the
+ * `run_subtask` tool. Kept in this leaf module (no imports) so the two
+ * modules don't have to import each other — importing across that boundary
+ * created a top-level-await cycle that deadlocked the bundled server.
+ */
+/** Context variable carrying the current subtask depth (0 at the chat root). */
+export const SUBTASK_DEPTH_KEY = "__subtask_depth";
+/** Reserved input-schema field StepExecutor sets to the LLM-provided tool_call_id. */
+export const TOOL_CALL_ID_FIELD = "_tool_call_id";
+//# sourceMappingURL=subtask-fields.js.map

package/dist/tools/subtask-fields.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subtask-fields.js","sourceRoot":"","sources":["../../src/tools/subtask-fields.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,gFAAgF;AAChF,MAAM,CAAC,MAAM,iBAAiB,GAAG,iBAAiB,CAAC;AAEnD,sFAAsF;AACtF,MAAM,CAAC,MAAM,kBAAkB,GAAG,eAAe,CAAC"}

package/dist/tools/todo-tools.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `todo_write` — task checklist for an agent run.
+ *
+ * The agent passes the *entire* todo list on every call (full replacement,
+ * not patch). The list is stored per chat-thread and broadcast to the UI via
+ * a `todo_update` ProcessingMessage so the chat sidebar can render it as a
+ * live checklist.
+ *
+ * The implementation and the per-thread store live in the `files` capability
+ * module (`../capabilities/files.ts`), with the store beside the one function
+ * that writes it; the three readers are re-exported here for their existing
+ * callers.
+ */
+export { getThreadTodos, clearThreadTodos, _resetTodoStoreForTests } from "../capabilities/files.js";
+//# sourceMappingURL=todo-tools.d.ts.map

package/dist/tools/todo-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"todo-tools.d.ts","sourceRoot":"","sources":["../../src/tools/todo-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,uBAAuB,EACxB,MAAM,0BAA0B,CAAC"}

package/dist/tools/todo-tools.js

@@ -0,0 +1,15 @@
+/**
+ * `todo_write` — task checklist for an agent run.
+ *
+ * The agent passes the *entire* todo list on every call (full replacement,
+ * not patch). The list is stored per chat-thread and broadcast to the UI via
+ * a `todo_update` ProcessingMessage so the chat sidebar can render it as a
+ * live checklist.
+ *
+ * The implementation and the per-thread store live in the `files` capability
+ * module (`../capabilities/files.ts`), with the store beside the one function
+ * that writes it; the three readers are re-exported here for their existing
+ * callers.
+ */
+export { getThreadTodos, clearThreadTodos, _resetTodoStoreForTests } from "../capabilities/files.js";
+//# sourceMappingURL=todo-tools.js.map

package/dist/tools/todo-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"todo-tools.js","sourceRoot":"","sources":["../../src/tools/todo-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,uBAAuB,EACxB,MAAM,0BAA0B,CAAC"}

package/dist/tools/tool-permissions.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Permission classification for the `Tool` classes that are not capabilities,
+ * plus the gate contract re-exported from `@nodetool-ai/runtime`.
+ *
+ * The chat agent always carries a fixed toolbelt; a permission *mode* decides
+ * whether each tool call runs automatically, asks the user first, or is
+ * blocked. The ladder itself lives in `capabilities/invoke.ts` — one
+ * implementation, reached either through `CapabilityRun.invoke` or through the
+ * `gateTools` wrapper (`capabilities/gate-tools.ts`), which is how a host that
+ * still hands out `Tool` instances gets the same gate. The wrapper lives on
+ * the capabilities side so this file never imports from `capabilities/` — the
+ * reverse edge deadlocked the bundled backend's async module wrappers.
+ *
+ * Design: docs/superpowers/specs/2026-05-28-chat-permission-model-design.md,
+ * docs/tool-class-retirement-design.md § "Where the permission gate lives"
+ */
+import type { PermissionCategory } from "@nodetool-ai/runtime";
+export { decidePermission, headlessDenialReason, headlessGate } from "@nodetool-ai/runtime";
+export type { ApprovalDecision, ApprovalRequest, PermissionCategory, PermissionDecision, PermissionGateOptions, PermissionMode, RequestApproval } from "@nodetool-ai/runtime";
+/**
+ * Tool name → category, for the `Tool` classes that are not capabilities.
+ *
+ * A capability's spec is the authority on its category, and
+ * `capabilityCategoryFor` (`capabilities/registry.ts`) reads the spec first
+ * and falls back to this map only for a name no spec owns. So this table holds
+ * exactly the surviving `Tool` classes: the plan-builder tools, `finish_step`,
+ * and `run_node`. An entry for a name that has a spec is a duplicate, and
+ * `tests/tool-permissions-spec-drift.test.ts` fails on one. Anything not
+ * listed anywhere defaults to `external`, the most conservative class, so a
+ * newly-added tool is gated until classified.
+ *
+ * `read` = no side effects (search, inspect, query, pure compute, internal
+ * agent bookkeeping). `write` = mutates local state or produces artifacts /
+ * costly media. `execute` = runs arbitrary compute. `external` = third-party
+ * side effects.
+ */
+export declare const TOOL_PERMISSION_CATEGORIES: Readonly<Record<string, PermissionCategory>>;
+/** Category for a tool name, defaulting to the conservative `external`. */
+export declare function permissionCategoryFor(name: string): PermissionCategory;
+//# sourceMappingURL=tool-permissions.d.ts.map

package/dist/tools/tool-permissions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-permissions.d.ts","sourceRoot":"","sources":["../../src/tools/tool-permissions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAM/D,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,YAAY,EACb,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,gBAAgB,EAChB,eAAe,EACf,kBAAkB,EAClB,kBAAkB,EAClB,qBAAqB,EACrB,cAAc,EACd,eAAe,EAChB,MAAM,sBAAsB,CAAC;AAE9B;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,0BAA0B,EAAE,QAAQ,CAC/C,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CASnC,CAAC;AAEF,2EAA2E;AAC3E,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,CAEtE"}

package/dist/tools/tool-permissions.js

@@ -0,0 +1,52 @@
+/**
+ * Permission classification for the `Tool` classes that are not capabilities,
+ * plus the gate contract re-exported from `@nodetool-ai/runtime`.
+ *
+ * The chat agent always carries a fixed toolbelt; a permission *mode* decides
+ * whether each tool call runs automatically, asks the user first, or is
+ * blocked. The ladder itself lives in `capabilities/invoke.ts` — one
+ * implementation, reached either through `CapabilityRun.invoke` or through the
+ * `gateTools` wrapper (`capabilities/gate-tools.ts`), which is how a host that
+ * still hands out `Tool` instances gets the same gate. The wrapper lives on
+ * the capabilities side so this file never imports from `capabilities/` — the
+ * reverse edge deadlocked the bundled backend's async module wrappers.
+ *
+ * Design: docs/superpowers/specs/2026-05-28-chat-permission-model-design.md,
+ * docs/tool-class-retirement-design.md § "Where the permission gate lives"
+ */
+// The gate contract (key, types, decision matrix, headless gate) lives in
+// `@nodetool-ai/runtime` so the workflow hosts below `agents` can set a gate
+// on the context they build. Re-exported here so every existing import of
+// these names keeps resolving through this module.
+export { decidePermission, headlessDenialReason, headlessGate } from "@nodetool-ai/runtime";
+/**
+ * Tool name → category, for the `Tool` classes that are not capabilities.
+ *
+ * A capability's spec is the authority on its category, and
+ * `capabilityCategoryFor` (`capabilities/registry.ts`) reads the spec first
+ * and falls back to this map only for a name no spec owns. So this table holds
+ * exactly the surviving `Tool` classes: the plan-builder tools, `finish_step`,
+ * and `run_node`. An entry for a name that has a spec is a duplicate, and
+ * `tests/tool-permissions-spec-drift.test.ts` fails on one. Anything not
+ * listed anywhere defaults to `external`, the most conservative class, so a
+ * newly-added tool is gated until classified.
+ *
+ * `read` = no side effects (search, inspect, query, pure compute, internal
+ * agent bookkeeping). `write` = mutates local state or produces artifacts /
+ * costly media. `execute` = runs arbitrary compute. `external` = third-party
+ * side effects.
+ */
+export const TOOL_PERMISSION_CATEGORIES = {
+    // Plan-builder bookkeeping: each edits the in-memory plan and nothing else.
+    finish_plan: "read",
+    add_task: "read",
+    remove_task: "read",
+    finish_step: "read",
+    // Runs one node with whatever that node does.
+    run_node: "execute"
+};
+/** Category for a tool name, defaulting to the conservative `external`. */
+export function permissionCategoryFor(name) {
+    return TOOL_PERMISSION_CATEGORIES[name] ?? "external";
+}
+//# sourceMappingURL=tool-permissions.js.map

package/dist/tools/tool-permissions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-permissions.js","sourceRoot":"","sources":["../../src/tools/tool-permissions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,0EAA0E;AAC1E,6EAA6E;AAC7E,0EAA0E;AAC1E,mDAAmD;AACnD,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,YAAY,EACb,MAAM,sBAAsB,CAAC;AAW9B;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAEnC;IACF,4EAA4E;IAC5E,WAAW,EAAE,MAAM;IACnB,QAAQ,EAAE,MAAM;IAChB,WAAW,EAAE,MAAM;IACnB,WAAW,EAAE,MAAM;IACnB,8CAA8C;IAC9C,QAAQ,EAAE,SAAS;CACpB,CAAC;AAEF,2EAA2E;AAC3E,MAAM,UAAU,qBAAqB,CAAC,IAAY;IAChD,OAAO,0BAA0B,CAAC,IAAI,CAAC,IAAI,UAAU,CAAC;AACxD,CAAC"}

package/dist/tools/tool-search.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Tool search — load deferred tool schemas on demand.
+ *
+ * A session keeps a small resident toolbelt and defers the long tail,
+ * announcing it by name in a `<system-reminder>`. The model pulls a schema in
+ * with `nodetool.searchTools()`, which reaches this ranking through the
+ * `__searchTools` host bridge and answers in the `<functions>` format the
+ * reminder promises. A provider that runs its own agent loop with native tool
+ * search (the Claude Agent SDK) uses its own built-in instead.
+ *
+ * Query grammar:
+ *   - `select:Name1,Name2`  — fetch these exact tools by name.
+ *   - `keyword words`        — keyword search over names + descriptions,
+ *                              best `max_results` matches.
+ *   - `+substr words`        — require `substr` in the tool name, rank by the
+ *                              remaining terms.
+ */
+import type { JsonSchema } from "@nodetool-ai/runtime";
+/** A deferred tool the model can load: name, description, and full schema. */
+export interface ToolSearchEntry {
+    name: string;
+    description?: string;
+    parameters?: JsonSchema | Record<string, unknown>;
+}
+export declare const TOOL_SEARCH_DESCRIPTION: string;
+/**
+ * Rank `catalog` against `query` per the Claude Code grammar and return the
+ * matching entries (at most `maxResults`, except `select:` which returns all
+ * named tools in the requested order).
+ */
+export declare function searchTools(catalog: readonly ToolSearchEntry[], query: string, maxResults?: number): ToolSearchEntry[];
+/** Render matched tools as the `<functions>` block the model expects. */
+export declare function formatToolSearchResult(entries: ToolSearchEntry[]): string;
+/**
+ * The `<system-reminder>` that announces deferred tools by name. The model
+ * loads any it needs with `nodetool.searchTools()` before calling them.
+ */
+export declare function formatDeferredToolsReminder(catalog: readonly ToolSearchEntry[]): string;
+//# sourceMappingURL=tool-search.d.ts.map

package/dist/tools/tool-search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-search.d.ts","sourceRoot":"","sources":["../../src/tools/tool-search.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAEvD,8EAA8E;AAC9E,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnD;AAED,eAAO,MAAM,uBAAuB,QAWsC,CAAC;AAE3E;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,SAAS,eAAe,EAAE,EACnC,KAAK,EAAE,MAAM,EACb,UAAU,SAAI,GACb,eAAe,EAAE,CA6CnB;AAED,yEAAyE;AACzE,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,MAAM,CAazE;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,SAAS,eAAe,EAAE,GAClC,MAAM,CAYR"}

package/dist/tools/tool-search.js

@@ -0,0 +1,108 @@
+/**
+ * Tool search — load deferred tool schemas on demand.
+ *
+ * A session keeps a small resident toolbelt and defers the long tail,
+ * announcing it by name in a `<system-reminder>`. The model pulls a schema in
+ * with `nodetool.searchTools()`, which reaches this ranking through the
+ * `__searchTools` host bridge and answers in the `<functions>` format the
+ * reminder promises. A provider that runs its own agent loop with native tool
+ * search (the Claude Agent SDK) uses its own built-in instead.
+ *
+ * Query grammar:
+ *   - `select:Name1,Name2`  — fetch these exact tools by name.
+ *   - `keyword words`        — keyword search over names + descriptions,
+ *                              best `max_results` matches.
+ *   - `+substr words`        — require `substr` in the tool name, rank by the
+ *                              remaining terms.
+ */
+export const TOOL_SEARCH_DESCRIPTION = "Fetches full schema definitions for deferred tools so they can be called. " +
+    "Deferred tools appear by name in <system-reminder> messages. Until fetched, " +
+    "only the name is known — there is no parameter schema, so the tool cannot be " +
+    "invoked. This tool takes a query, matches it against the deferred tool list, " +
+    "and returns the matched tools' complete JSONSchema definitions inside a " +
+    "<functions> block. Once a tool's schema appears in that result, it is " +
+    "callable exactly like any tool defined up front.\n\n" +
+    "Query forms:\n" +
+    '- "select:Read,Edit,Grep" — fetch these exact tools by name\n' +
+    '- "notebook jupyter" — keyword search, up to max_results best matches\n' +
+    '- "+slack send" — require "slack" in the name, rank by remaining terms';
+/**
+ * Rank `catalog` against `query` per the Claude Code grammar and return the
+ * matching entries (at most `maxResults`, except `select:` which returns all
+ * named tools in the requested order).
+ */
+export function searchTools(catalog, query, maxResults = 5) {
+    const q = (query ?? "").trim();
+    if (!q)
+        return [];
+    // `select:` — exact names, returned in the order requested.
+    if (q.toLowerCase().startsWith("select:")) {
+        const byName = new Map(catalog.map((e) => [e.name, e]));
+        const seen = new Set();
+        const out = [];
+        for (const name of q.slice("select:".length).split(",")) {
+            const trimmed = name.trim();
+            const entry = byName.get(trimmed);
+            if (entry && !seen.has(trimmed)) {
+                seen.add(trimmed);
+                out.push(entry);
+            }
+        }
+        return out;
+    }
+    // `+substr` — first token (sans `+`) must appear in the tool name.
+    let requiredNameSubstr;
+    let terms = q.toLowerCase().split(/\s+/).filter(Boolean);
+    if (q.startsWith("+") && terms.length > 0) {
+        requiredNameSubstr = terms[0].slice(1);
+        terms = terms.slice(1);
+    }
+    const scored = [];
+    for (const entry of catalog) {
+        const nameLower = entry.name.toLowerCase();
+        if (requiredNameSubstr && !nameLower.includes(requiredNameSubstr))
+            continue;
+        const descLower = (entry.description ?? "").toLowerCase();
+        let score = requiredNameSubstr ? 1 : 0;
+        for (const term of terms) {
+            if (nameLower.includes(term))
+                score += 3;
+            if (descLower.includes(term))
+                score += 1;
+        }
+        // A bare `+substr` with no extra terms still surfaces every name match.
+        if (score > 0 || terms.length === 0)
+            scored.push({ entry, score });
+    }
+    scored.sort((a, b) => b.score - a.score || a.entry.name.localeCompare(b.entry.name));
+    return scored.slice(0, Math.max(0, maxResults)).map((s) => s.entry);
+}
+/** Render matched tools as the `<functions>` block the model expects. */
+export function formatToolSearchResult(entries) {
+    if (entries.length === 0) {
+        return "No matching tools found. Try different keywords or a select: query.";
+    }
+    const lines = entries.map((e) => `<function>${JSON.stringify({
+        description: e.description ?? "",
+        name: e.name,
+        parameters: e.parameters ?? { type: "object", properties: {} }
+    })}</function>`);
+    return `<functions>\n${lines.join("\n")}\n</functions>`;
+}
+/**
+ * The `<system-reminder>` that announces deferred tools by name. The model
+ * loads any it needs with `nodetool.searchTools()` before calling them.
+ */
+export function formatDeferredToolsReminder(catalog) {
+    if (catalog.length === 0)
+        return "";
+    const names = catalog.map((e) => e.name).join(", ");
+    return ("<system-reminder>\n" +
+        "The following tools are available but their schemas are NOT loaded — " +
+        "calling them directly will fail. Use ToolSearch to load a tool's schema " +
+        'before calling it (e.g. ToolSearch with query "select:<name>", or ' +
+        "keywords to discover relevant tools):\n" +
+        names +
+        "\n</system-reminder>");
+}
+//# sourceMappingURL=tool-search.js.map

package/dist/tools/tool-search.js.map

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

package/dist/tools/vector-tool-support.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Pure helpers behind the vector capabilities: metadata flattening, the
+ * document-id derivation, and the two text splitters.
+ *
+ * They used to be module-private inside `vector-tools.ts` (`splitTextRecursive`
+ * exported for its regression test). The `collections` capability module
+ * (`../capabilities/collections.ts`) needs the same functions, and a capability
+ * module must not import the tool module it replaces, so they live here and
+ * both sides import them.
+ */
+export declare function flattenMetadata(obj: Record<string, unknown>): Record<string, string | number | boolean>;
+export declare function generateDocumentId(sourceId: string): string;
+export declare function splitTextRecursive(text: string, separators: string[], chunkSize: number, chunkOverlap: number): string[];
+export declare function splitMarkdownByHeaders(text: string): string[];
+//# sourceMappingURL=vector-tool-support.d.ts.map

package/dist/tools/vector-tool-support.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vector-tool-support.d.ts","sourceRoot":"","sources":["../../src/tools/vector-tool-support.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AASH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,6CAW7B;AAED,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAAE,EACpB,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,GACnB,MAAM,EAAE,CA4FV;AAED,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAgB7D"}

package/dist/tools/vector-tool-support.js

@@ -0,0 +1,133 @@
+/**
+ * Pure helpers behind the vector capabilities: metadata flattening, the
+ * document-id derivation, and the two text splitters.
+ *
+ * They used to be module-private inside `vector-tools.ts` (`splitTextRecursive`
+ * exported for its regression test). The `collections` capability module
+ * (`../capabilities/collections.ts`) needs the same functions, and a capability
+ * module must not import the tool module it replaces, so they live here and
+ * both sides import them.
+ */
+import { createHash } from "node:crypto";
+import { isBoolean, isNumber, isString } from "../utils/type-guards.js";
+export function flattenMetadata(obj) {
+    const out = {};
+    for (const [k, v] of Object.entries(obj ?? {})) {
+        if (isString(v) || isNumber(v) || isBoolean(v)) {
+            out[k] = v;
+        }
+        else if (v !== null && v !== undefined) {
+            out[k] = String(v);
+        }
+    }
+    return out;
+}
+export function generateDocumentId(sourceId) {
+    return `${sourceId}-${createHash("md5").update(sourceId).digest("hex").slice(0, 8)}`;
+}
+export function splitTextRecursive(text, separators, chunkSize, chunkOverlap) {
+    // Clamp params so the sliding window always advances. chunk_size/overlap come
+    // straight from model-supplied args; if overlap >= size the stride
+    // `chunkSize - chunkOverlap` is <= 0 and the while-loops below spin forever
+    // (event-loop hang + unbounded chunks[] → OOM). Guarantee 1 <= size and
+    // 0 <= overlap < size.
+    chunkSize = Math.max(1, Math.floor(chunkSize));
+    chunkOverlap = Math.min(Math.max(0, Math.floor(chunkOverlap)), chunkSize - 1);
+    if (text.length <= chunkSize)
+        return [text];
+    // Find first separator that appears in text
+    let sep = null;
+    for (const s of separators) {
+        if (text.includes(s)) {
+            sep = s;
+            break;
+        }
+    }
+    // If no separator found, split by chunk size
+    if (sep === null) {
+        const chunks = [];
+        let start = 0;
+        while (start < text.length) {
+            chunks.push(text.slice(start, start + chunkSize));
+            start += chunkSize - chunkOverlap;
+            if (start + chunkOverlap >= text.length && start < text.length) {
+                chunks.push(text.slice(start));
+                break;
+            }
+        }
+        return chunks;
+    }
+    const splits = text.split(sep).filter((s) => s.length > 0);
+    const remainingSeparators = separators.slice(separators.indexOf(sep) + 1);
+    // Merge splits into chunks
+    const chunks = [];
+    let current = "";
+    for (const split of splits) {
+        const candidate = current ? current + sep + split : split;
+        if (candidate.length <= chunkSize) {
+            current = candidate;
+        }
+        else {
+            if (current)
+                chunks.push(current);
+            if (split.length > chunkSize && remainingSeparators.length > 0) {
+                const subChunks = splitTextRecursive(split, remainingSeparators, chunkSize, chunkOverlap);
+                chunks.push(...subChunks);
+                current = "";
+            }
+            else if (split.length > chunkSize) {
+                // No more separators, force-split
+                let start = 0;
+                while (start < split.length) {
+                    chunks.push(split.slice(start, start + chunkSize));
+                    start += chunkSize - chunkOverlap;
+                    if (start + chunkOverlap >= split.length && start < split.length) {
+                        chunks.push(split.slice(start));
+                        break;
+                    }
+                }
+                current = "";
+            }
+            else {
+                current = split;
+            }
+        }
+    }
+    if (current)
+        chunks.push(current);
+    // Apply overlap between merged chunks
+    if (chunkOverlap > 0 && chunks.length > 1) {
+        const overlapped = [chunks[0]];
+        for (let i = 1; i < chunks.length; i++) {
+            const prev = chunks[i - 1];
+            const overlapText = prev.slice(Math.max(0, prev.length - chunkOverlap));
+            const merged = overlapText + sep + chunks[i];
+            if (merged.length <= chunkSize) {
+                overlapped.push(merged);
+            }
+            else {
+                overlapped.push(chunks[i]);
+            }
+        }
+        return overlapped;
+    }
+    return chunks;
+}
+export function splitMarkdownByHeaders(text) {
+    const headerRegex = /^(#{1,3})\s+/m;
+    const sections = [];
+    let current = "";
+    for (const line of text.split("\n")) {
+        if (headerRegex.test(line) && current.trim()) {
+            sections.push(current.trim());
+            current = line + "\n";
+        }
+        else {
+            current += line + "\n";
+        }
+    }
+    if (current.trim())
+        sections.push(current.trim());
+    return sections;
+}
+//# sourceMappingURL=vector-tool-support.js.map

package/dist/tools/vector-tool-support.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vector-tool-support.js","sourceRoot":"","sources":["../../src/tools/vector-tool-support.ts"],"names":[],"mappings":"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"}