@nexustools/aitooling

Key Capabilities

Installation

npm install @nexustools/aitooling@beta

Quick Start

1. Creating Tools & Using ContextualToolRegistry

import {
    AbstractAiTool,
    ContextualToolRegistry,
    AiToolDefinition,
    AiToolExecutionResult
} from "@nexustools/aitooling";

interface AppAgentContext {
    hasPlan: boolean;
    taskList: string[];
    workspaceDir: string;
}

class CreatePlanTool extends AbstractAiTool<AppAgentContext> {
    readonly name = "create_plan";
    readonly description = "Create the implementation plan before writing code.";
    protected readonly parameters: AiToolDefinition["function"]["parameters"] = {
        type: "object",
        properties: {
            tasks: { type: "array", items: { type: "string" }, description: "Ordered list of tasks" }
        },
        required: ["tasks"]
    };

    async execute(args: Record<string, any>, context: AppAgentContext): Promise<AiToolExecutionResult> {
        context.taskList = Array.isArray(args.tasks) ? args.tasks : [];
        context.hasPlan = context.taskList.length > 0;
        return { ok: true, summary: `Created plan with ${context.taskList.length} tasks.` };
    }
}

class EditFilesTool extends AbstractAiTool<AppAgentContext> {
    readonly name = "edit_files";
    readonly description = "Edit project source files (only unlocked after a plan is created).";
    protected readonly parameters: AiToolDefinition["function"]["parameters"] = {
        type: "object",
        properties: {
            path: { type: "string" },
            content: { type: "string" }
        },
        required: ["path", "content"]
    };

    async execute(args: Record<string, any>, context: AppAgentContext): Promise<AiToolExecutionResult> {
        return { ok: true, summary: `Edited ${args.path} in ${context.workspaceDir}` };
    }
}

const registry = new ContextualToolRegistry<AppAgentContext>();

// Available before a plan exists:
registry.register(new CreatePlanTool(), { hideAfterPlanOrTaskList: true });

// Only unlocked AFTER a plan or task list is created:
registry.register(new EditFilesTool(), {
    requiresPlanOrTaskList: true,
    enforcePlanGate: true
});

2. Implementing a Custom AI Service Provider via Code

import {
    AiProviderRegistry,
    CustomAiServiceAdapter,
    LmStudioAiClient
} from "@nexustools/aitooling";

const myCustomAdapter: CustomAiServiceAdapter = {
    id: "my-company-llm",
    displayName: "My Company Internal LLM",
    async listModels(config) {
        return [{ id: "company-coder-70b", object: "model", owned_by: "internal" }];
    },
    async streamChatTurn({ messages, tools, callbacks, abortSignal, config }) {
        callbacks?.onContentDelta?.("Hello from custom provider!");
        return {
            assistantMessage: {
                role: "assistant",
                content: "Hello from custom provider!"
            }
        };
    }
};

// Register globally so any LmStudioAiClient / MultiProviderToolStreamClient can use it:
AiProviderRegistry.registerProvider(myCustomAdapter);

const client = new LmStudioAiClient({
    provider: "my-company-llm",
    model: "company-coder-70b"
});

3. Live-Parsing AI Chat UI (AiLiveChatController)

import { AiLiveChatController, LmStudioAiClient } from "@nexustools/aitooling";

const client = new LmStudioAiClient({
    provider: "openai",
    apiKey: process.env.OPENAI_API_KEY,
    model: "gpt-4o"
});

const chatUi = new AiLiveChatController({
    messagesContainer: document.getElementById("chat-messages")!,
    statusBadgeEl: document.getElementById("ai-status")!,
    sendButtonEl: document.getElementById("btn-send") as HTMLButtonElement,
    stopButtonEl: document.getElementById("btn-stop") as HTMLButtonElement,
    client
});

await chatUi.sendMessage("Create a plan and build the login component.");

Documentation