Forked from harshallmstudio/document-streamer
Forked from harshallmstudio/document-streamer
src / toolsProvider.ts
import {
tool,
type Tool,
type ToolsProviderController,
} from "@lmstudio/sdk";
import path from "node:path";
import { z } from "zod";
import { configSchematics } from "./config";
import { parseDocumentFile } from "./documentParser";
import { documentStore } from "./documentStore";
import { resolveReadableDocument } from "./pathGuard";
export async function toolsProvider(
ctl: ToolsProviderController,
): Promise<Tool[]> {
const openDocument = tool({
name: "open_document",
description:
"Open a supported local document and return its documentId and first chunk. " +
"Always call this tool before reading chunks, including in a new chat or after " +
"a session-not-found error. Document IDs are temporary and cannot be reused " +
"after expiration or a plugin reload. Continue reading chunks until hasMore is false.",
parameters: {
path: z
.string()
.describe(
"Absolute document path, or a path relative to the working directory.",
),
},
implementation: async (
{ path: requestedPath },
{ status, warn, signal },
) => {
try {
signal.throwIfAborted();
const config = ctl.getPluginConfig(configSchematics);
const allowedDirectories = config.get("allowedDirectories");
const chunkCharacters = config.get("chunkCharacters");
const configuredOverlap = config.get("chunkOverlap");
const overlapCharacters = Math.min(
configuredOverlap,
Math.max(0, chunkCharacters - 1),
);
const maxFileSizeMb = config.get("maxFileSizeMb");
const maxFileSizeBytes = maxFileSizeMb * 1024 * 1024;
const sessionTtlMinutes = config.get("sessionTtlMinutes");
documentStore.pruneExpiredDocuments(sessionTtlMinutes);
const resolved = await resolveReadableDocument(
requestedPath,
ctl.getWorkingDirectory(),
allowedDirectories,
);
if (resolved.size > maxFileSizeBytes) {
return `Error: File size exceeds the configured limit of ${maxFileSizeMb} MB.`;
}
status(`Parsing ${path.basename(resolved.filePath)}...`);
const parsed = await parseDocumentFile(
resolved.filePath,
maxFileSizeBytes,
);
signal.throwIfAborted();
const document = documentStore.createDocument({
filePath: resolved.filePath,
parsed,
chunkCharacters,
overlapCharacters,
});
status(`Opened ${document.fileName}.`);
return JSON.stringify({
documentId: document.id,
fileName: document.fileName,
format: document.format,
totalCharacters: document.text.length,
totalChunks: document.chunks.length,
currentChunk: 1,
firstChunk: document.chunks[0],
nextAction:
document.chunks.length > 1
? `Call read_document_chunk with documentId "${document.id}" and chunkNumber 2.`
: "The entire extracted document is contained in this response.",
});
} catch (error) {
if (signal.aborted) {
return "Document opening was cancelled.";
}
return `Error: ${
error instanceof Error ? error.message : String(error)
}`;
}
},
});
const readDocumentChunk = tool({
name: "read_document_chunk",
description:
"Read one chunk from a document opened during the current plugin session. " +
"Use the exact documentId returned by open_document. If the session is missing " +
"or expired, call open_document again with the original file path; do not ask " +
"the user for a document ID.",
parameters: {
documentId: z
.string()
.describe("Document identifier returned by open_document."),
chunkNumber: z.number().int().min(1).describe("One-based chunk number."),
},
implementation: async ({ documentId, chunkNumber }) => {
const document = documentStore.getDocument(documentId);
if (!document) {
return JSON.stringify({
error: "DOCUMENT_SESSION_UNAVAILABLE",
message:
"The document session expired or the plugin was reloaded. " +
"Call open_document again using the original file path. " +
"Do not ask the user to provide a document ID.",
documentId,
});
}
if (chunkNumber > document.chunks.length) {
return `Error: chunkNumber must be between 1 and ${document.chunks.length}.`;
}
const chunk = document.chunks[chunkNumber - 1];
return JSON.stringify({
documentId: document.id,
fileName: document.fileName,
chunkNumber,
totalChunks: document.chunks.length,
startCharacter: chunk.startCharacter,
endCharacter: chunk.endCharacter,
hasMore: chunkNumber < document.chunks.length,
nextAction:
chunkNumber < document.chunks.length
? `Analyze this chunk, then request chunk ${chunkNumber + 1} if more content is needed.`
: "This is the final chunk. Combine the chunk analyses to answer the user's request.",
text: chunk.text,
});
},
});
const closeDocumentTool = tool({
name: "close_document",
description: "Release an open document and its extracted text from memory.",
parameters: {
documentId: z
.string()
.describe("Document identifier returned by open_document."),
},
implementation: async ({ documentId }) => {
return documentStore.closeDocument(documentId)
? `Closed document session ${documentId}.`
: "Document session was not found or had already expired.";
},
});
const inspectDocument = tool({
name: "inspect_document",
description:
"Check whether a document session is still available and report its chunk count. Use only with an ID returned by open_document in the current plugin session.",
parameters: {
documentId: z.string().describe("Document ID returned by open_document."),
},
implementation: async ({ documentId }) => {
const document = documentStore.getDocument(documentId);
if (!document) {
return JSON.stringify({
found: false,
action:
"Call open_document again with the original file path. " +
"Sessions do not survive expiration or plugin reloads.",
});
}
return JSON.stringify({
documentId: document.id,
fileName: document.fileName,
totalChunks: document.chunks.length,
lastAccessedAt: new Date(document.lastAccessedAt).toISOString(),
});
},
});
return [
openDocument,
readDocumentChunk,
inspectDocument,
closeDocumentTool,
];
}
src / toolsProvider.ts
import {
tool,
type Tool,
type ToolsProviderController,
} from "@lmstudio/sdk";
import path from "node:path";
import { z } from "zod";
import { configSchematics } from "./config";
import { parseDocumentFile } from "./documentParser";
import { documentStore } from "./documentStore";
import { resolveReadableDocument } from "./pathGuard";
export async function toolsProvider(
ctl: ToolsProviderController,
): Promise<Tool[]> {
const openDocument = tool({
name: "open_document",
description:
"Open a supported local document and return its documentId and first chunk. " +
"Always call this tool before reading chunks, including in a new chat or after " +
"a session-not-found error. Document IDs are temporary and cannot be reused " +
"after expiration or a plugin reload. Continue reading chunks until hasMore is false.",
parameters: {
path: z
.string()
.describe(
"Absolute document path, or a path relative to the working directory.",
),
},
implementation: async (
{ path: requestedPath },
{ status, warn, signal },
) => {
try {
signal.throwIfAborted();
const config = ctl.getPluginConfig(configSchematics);
const allowedDirectories = config.get("allowedDirectories");
const chunkCharacters = config.get("chunkCharacters");
const configuredOverlap = config.get("chunkOverlap");
const overlapCharacters = Math.min(
configuredOverlap,
Math.max(0, chunkCharacters - 1),
);
const maxFileSizeMb = config.get("maxFileSizeMb");
const maxFileSizeBytes = maxFileSizeMb * 1024 * 1024;
const sessionTtlMinutes = config.get("sessionTtlMinutes");
documentStore.pruneExpiredDocuments(sessionTtlMinutes);
const resolved = await resolveReadableDocument(
requestedPath,
ctl.getWorkingDirectory(),
allowedDirectories,
);
if (resolved.size > maxFileSizeBytes) {
return `Error: File size exceeds the configured limit of ${maxFileSizeMb} MB.`;
}
status(`Parsing ${path.basename(resolved.filePath)}...`);
const parsed = await parseDocumentFile(
resolved.filePath,
maxFileSizeBytes,
);
signal.throwIfAborted();
const document = documentStore.createDocument({
filePath: resolved.filePath,
parsed,
chunkCharacters,
overlapCharacters,
});
status(`Opened ${document.fileName}.`);
return JSON.stringify({
documentId: document.id,
fileName: document.fileName,
format: document.format,
totalCharacters: document.text.length,
totalChunks: document.chunks.length,
currentChunk: 1,
firstChunk: document.chunks[0],
nextAction:
document.chunks.length > 1
? `Call read_document_chunk with documentId "${document.id}" and chunkNumber 2.`
: "The entire extracted document is contained in this response.",
});
} catch (error) {
if (signal.aborted) {
return "Document opening was cancelled.";
}
return `Error: ${
error instanceof Error ? error.message : String(error)
}`;
}
},
});
const readDocumentChunk = tool({
name: "read_document_chunk",
description:
"Read one chunk from a document opened during the current plugin session. " +
"Use the exact documentId returned by open_document. If the session is missing " +
"or expired, call open_document again with the original file path; do not ask " +
"the user for a document ID.",
parameters: {
documentId: z
.string()
.describe("Document identifier returned by open_document."),
chunkNumber: z.number().int().min(1).describe("One-based chunk number."),
},
implementation: async ({ documentId, chunkNumber }) => {
const document = documentStore.getDocument(documentId);
if (!document) {
return JSON.stringify({
error: "DOCUMENT_SESSION_UNAVAILABLE",
message:
"The document session expired or the plugin was reloaded. " +
"Call open_document again using the original file path. " +
"Do not ask the user to provide a document ID.",
documentId,
});
}
if (chunkNumber > document.chunks.length) {
return `Error: chunkNumber must be between 1 and ${document.chunks.length}.`;
}
const chunk = document.chunks[chunkNumber - 1];
return JSON.stringify({
documentId: document.id,
fileName: document.fileName,
chunkNumber,
totalChunks: document.chunks.length,
startCharacter: chunk.startCharacter,
endCharacter: chunk.endCharacter,
hasMore: chunkNumber < document.chunks.length,
nextAction:
chunkNumber < document.chunks.length
? `Analyze this chunk, then request chunk ${chunkNumber + 1} if more content is needed.`
: "This is the final chunk. Combine the chunk analyses to answer the user's request.",
text: chunk.text,
});
},
});
const closeDocumentTool = tool({
name: "close_document",
description: "Release an open document and its extracted text from memory.",
parameters: {
documentId: z
.string()
.describe("Document identifier returned by open_document."),
},
implementation: async ({ documentId }) => {
return documentStore.closeDocument(documentId)
? `Closed document session ${documentId}.`
: "Document session was not found or had already expired.";
},
});
const inspectDocument = tool({
name: "inspect_document",
description:
"Check whether a document session is still available and report its chunk count. Use only with an ID returned by open_document in the current plugin session.",
parameters: {
documentId: z.string().describe("Document ID returned by open_document."),
},
implementation: async ({ documentId }) => {
const document = documentStore.getDocument(documentId);
if (!document) {
return JSON.stringify({
found: false,
action:
"Call open_document again with the original file path. " +
"Sessions do not survive expiration or plugin reloads.",
});
}
return JSON.stringify({
documentId: document.id,
fileName: document.fileName,
totalChunks: document.chunks.length,
lastAccessedAt: new Date(document.lastAccessedAt).toISOString(),
});
},
});
return [
openDocument,
readDocumentChunk,
inspectDocument,
closeDocumentTool,
];
}