@termaxjs/web-ai 0.1.1

package/dist/tools/fs.d.ts

@@ -0,0 +1,93 @@
+import { type ToolContext } from "./context.js";
+export declare function buildFsTools(ctx: ToolContext): {
+    readonly read_file: import("ai").Tool<{
+        path: string;
+        offset?: number | undefined;
+        limit?: number | undefined;
+    }, {
+        error: string;
+        path: string;
+        size?: undefined;
+        unchanged?: undefined;
+    } | {
+        error: string;
+        path: string;
+        size: any;
+        unchanged?: undefined;
+    } | {
+        path: string;
+        unchanged: boolean;
+        size: any;
+        error?: undefined;
+    } | {
+        truncated?: boolean | undefined;
+        hint?: string | undefined;
+        path: string;
+        content: any;
+        size: any;
+        total_lines: any;
+        error?: undefined;
+        unchanged?: undefined;
+    } | {
+        truncated?: boolean | undefined;
+        path: string;
+        content: any;
+        size: any;
+        total_lines: any;
+        start_line: number;
+        end_line: number;
+        error?: undefined;
+        unchanged?: undefined;
+    }>;
+    readonly list_directory: import("ai").Tool<{
+        path: string;
+    }, {
+        error: string;
+        path: string;
+        entries?: undefined;
+    } | {
+        path: string;
+        entries: any;
+        error?: undefined;
+    }>;
+    readonly write_file: import("ai").Tool<{
+        path: string;
+        content: string;
+    }, {
+        error: string;
+        path: string;
+        queued_for_plan_review?: undefined;
+        ok?: undefined;
+        bytesWritten?: undefined;
+    } | {
+        path: string;
+        queued_for_plan_review: boolean;
+        ok: boolean;
+        error?: undefined;
+        bytesWritten?: undefined;
+    } | {
+        path: string;
+        bytesWritten: number;
+        ok: boolean;
+        error?: undefined;
+        queued_for_plan_review?: undefined;
+    }>;
+    readonly create_directory: import("ai").Tool<{
+        path: string;
+    }, {
+        error: string;
+        path: string;
+        queued_for_plan_review?: undefined;
+        ok?: undefined;
+    } | {
+        path: string;
+        queued_for_plan_review: boolean;
+        ok: boolean;
+        error?: undefined;
+    } | {
+        path: string;
+        ok: boolean;
+        error?: undefined;
+        queued_for_plan_review?: undefined;
+    }>;
+};

package/dist/tools/fs.js

@@ -0,0 +1,215 @@
+import { tool } from "ai";
+import { z } from "zod";
+import { getAiAdapter } from "../config.js";
+import { checkReadableCanonical, checkWritableCanonical, } from "../lib/security.js";
+import { resolvePath } from "./context.js";
+const READ_BYTE_CAP = 25 * 1024;
+const READ_LINE_CAP = 2000;
+function djb2(s) {
+    let h = 5381;
+    for (let i = 0; i < s.length; i++)
+        h = ((h << 5) + h + s.charCodeAt(i)) | 0;
+    return h >>> 0;
+}
+export function buildFsTools(ctx) {
+    return {
+        read_file: tool({
+            description: "Read a UTF-8 text file. Defaults to the first 2000 lines (capped at 25KB). Pass `offset`/`limit` for line-based windowing of large files. Refuses binary, oversized, or sensitive files (.env, keys, credentials). If you call this on the same path twice in a session without edits in between, the second call returns `unchanged: true` instead of re-emitting the content — re-read the prior tool result.",
+            inputSchema: z.object({
+                path: z
+                    .string()
+                    .describe("Absolute path, or relative to the active terminal cwd."),
+                offset: z
+                    .number()
+                    .int()
+                    .min(0)
+                    .optional()
+                    .describe("0-based start line. Default 0."),
+                limit: z
+                    .number()
+                    .int()
+                    .min(1)
+                    .max(10000)
+                    .optional()
+                    .describe("Max lines to return. Default 2000."),
+            }),
+            execute: async ({ path, offset, limit }) => {
+                const reqPath = resolvePath(path, ctx.getCwd());
+                const safety = await checkReadableCanonical(reqPath, getAiAdapter().native.canonicalize);
+                if (!safety.ok)
+                    return { error: safety.reason, path: reqPath };
+                const abs = safety.canonical;
+                try {
+                    const r = await getAiAdapter().native.readFile(abs);
+                    if (r.kind === "binary")
+                        return { error: "binary file refused", path: abs, size: r.size };
+                    if (r.kind === "toolarge")
+                        return {
+                            error: `file too large (${r.size} bytes, limit ${r.limit})`,
+                            path: abs,
+                        };
+                    const hash = djb2(r.content);
+                    const isFullRead = offset === undefined && limit === undefined;
+                    const prior = ctx.readCache.get(abs);
+                    if (isFullRead &&
+                        prior &&
+                        prior.size === r.size &&
+                        prior.hash === hash) {
+                        return { path: abs, unchanged: true, size: r.size };
+                    }
+                    ctx.readCache.set(abs, { size: r.size, hash });
+                    if (isFullRead) {
+                        const lines = r.content.split("\n");
+                        const sliceEnd = Math.min(lines.length, READ_LINE_CAP);
+                        let content = lines.slice(0, sliceEnd).join("\n");
+                        let truncated = sliceEnd < lines.length;
+                        if (content.length > READ_BYTE_CAP) {
+                            content = content.slice(0, READ_BYTE_CAP);
+                            truncated = true;
+                        }
+                        return {
+                            path: abs,
+                            content,
+                            size: r.size,
+                            total_lines: lines.length,
+                            ...(truncated
+                                ? {
+                                    truncated: true,
+                                    hint: "call read_file with offset to continue",
+                                }
+                                : {}),
+                        };
+                    }
+                    const lines = r.content.split("\n");
+                    const start = offset ?? 0;
+                    const requested = limit ?? READ_LINE_CAP;
+                    const end = Math.min(lines.length, start + requested);
+                    let content = lines.slice(start, end).join("\n");
+                    let truncated = end < lines.length;
+                    if (content.length > READ_BYTE_CAP) {
+                        content = content.slice(0, READ_BYTE_CAP);
+                        truncated = true;
+                    }
+                    return {
+                        path: abs,
+                        content,
+                        size: r.size,
+                        total_lines: lines.length,
+                        start_line: start,
+                        end_line: end,
+                        ...(truncated ? { truncated: true } : {}),
+                    };
+                }
+                catch (e) {
+                    return { error: String(e), path: abs };
+                }
+            },
+        }),
+        list_directory: tool({
+            description: "List immediate entries (files + directories) in a directory. Hidden entries are omitted.",
+            inputSchema: z.object({
+                path: z
+                    .string()
+                    .describe("Absolute path, or relative to the active terminal cwd."),
+            }),
+            execute: async ({ path }) => {
+                const reqPath = resolvePath(path, ctx.getCwd());
+                const safety = await checkReadableCanonical(reqPath, getAiAdapter().native.canonicalize);
+                if (!safety.ok)
+                    return { error: safety.reason, path: reqPath };
+                const abs = safety.canonical;
+                try {
+                    const entries = await getAiAdapter().native.readDir(abs);
+                    return {
+                        path: abs,
+                        entries: entries.map((e) => ({ name: e.name, kind: e.kind })),
+                    };
+                }
+                catch (e) {
+                    return { error: String(e), path: abs };
+                }
+            },
+        }),
+        write_file: tool({
+            description: "Create or overwrite a file with the given content. Always asks the user before running. Prefer `edit` / `multi_edit` for in-place changes — only use `write_file` for creating a brand-new file or fully replacing a tiny one.",
+            inputSchema: z.object({
+                path: z.string(),
+                content: z.string(),
+            }),
+            needsApproval: true,
+            execute: async ({ path, content }) => {
+                const reqPath = resolvePath(path, ctx.getCwd());
+                const safety = await checkWritableCanonical(reqPath, getAiAdapter().native.canonicalize);
+                if (!safety.ok)
+                    return { error: safety.reason, path: reqPath };
+                const abs = safety.canonical;
+                if (getAiAdapter().isPlanActive()) {
+                    let original = "";
+                    let isNewFile = false;
+                    try {
+                        const r = await getAiAdapter().native.readFile(abs);
+                        if (r.kind === "text")
+                            original = r.content;
+                    }
+                    catch {
+                        isNewFile = true;
+                    }
+                    getAiAdapter().enqueuePlanEdit({
+                        id: crypto.randomUUID(),
+                        kind: "write_file",
+                        path: abs,
+                        originalContent: original,
+                        proposedContent: content,
+                        isNewFile,
+                    });
+                    return {
+                        path: abs,
+                        queued_for_plan_review: true,
+                        ok: true,
+                    };
+                }
+                try {
+                    await getAiAdapter().native.writeFile(abs, content);
+                    ctx.readCache.set(abs, { size: content.length, hash: djb2(content) });
+                    return { path: abs, bytesWritten: content.length, ok: true };
+                }
+                catch (e) {
+                    return { error: String(e), path: abs };
+                }
+            },
+        }),
+        create_directory: tool({
+            description: "Create a directory (and any missing parents). Always asks the user before running.",
+            inputSchema: z.object({
+                path: z.string(),
+            }),
+            needsApproval: true,
+            execute: async ({ path }) => {
+                const reqPath = resolvePath(path, ctx.getCwd());
+                const safety = await checkWritableCanonical(reqPath, getAiAdapter().native.canonicalize);
+                if (!safety.ok)
+                    return { error: safety.reason, path: reqPath };
+                const abs = safety.canonical;
+                if (getAiAdapter().isPlanActive()) {
+                    getAiAdapter().enqueuePlanEdit({
+                        id: crypto.randomUUID(),
+                        kind: "create_directory",
+                        path: abs,
+                        originalContent: "",
+                        proposedContent: "",
+                        isNewFile: true,
+                        description: "Create directory",
+                    });
+                    return { path: abs, queued_for_plan_review: true, ok: true };
+                }
+                try {
+                    await getAiAdapter().native.createDir(abs);
+                    return { path: abs, ok: true };
+                }
+                catch (e) {
+                    return { error: String(e), path: abs };
+                }
+            },
+        }),
+    };
+}

package/dist/tools/search.d.ts

@@ -0,0 +1,48 @@
+import { type ToolContext } from "./context.js";
+export declare function buildSearchTools(ctx: ToolContext): {
+    readonly grep: import("ai").Tool<{
+        pattern: string;
+        root?: string | undefined;
+        glob?: string[] | undefined;
+        case_insensitive?: boolean | undefined;
+        max_results?: number | undefined;
+    }, {
+        error: string;
+        root?: undefined;
+        hits?: undefined;
+        truncated?: undefined;
+        files_scanned?: undefined;
+    } | {
+        error: string;
+        root: string;
+        hits?: undefined;
+        truncated?: undefined;
+        files_scanned?: undefined;
+    } | {
+        root: string;
+        hits: any;
+        truncated: any;
+        files_scanned: any;
+        error?: undefined;
+    }>;
+    readonly glob: import("ai").Tool<{
+        pattern: string;
+        root?: string | undefined;
+        max_results?: number | undefined;
+    }, {
+        error: string;
+        root?: undefined;
+        hits?: undefined;
+        truncated?: undefined;
+    } | {
+        error: string;
+        root: string;
+        hits?: undefined;
+        truncated?: undefined;
+    } | {
+        root: string;
+        hits: any;
+        truncated: any;
+        error?: undefined;
+    }>;
+};

package/dist/tools/search.js

@@ -0,0 +1,118 @@
+import { tool } from "ai";
+import { z } from "zod";
+import { getAiAdapter } from "../config.js";
+import { checkReadableCanonical } from "../lib/security.js";
+import { resolvePath } from "./context.js";
+function resolveRoot(rawRoot, ctx) {
+    if (rawRoot && rawRoot.trim().length > 0) {
+        try {
+            return { ok: true, path: resolvePath(rawRoot, ctx.getCwd()) };
+        }
+        catch (e) {
+            return { ok: false, error: String(e) };
+        }
+    }
+    const ws = ctx.getWorkspaceRoot();
+    if (ws)
+        return { ok: true, path: ws };
+    const cwd = ctx.getCwd();
+    if (cwd)
+        return { ok: true, path: cwd };
+    return {
+        ok: false,
+        error: "no workspace root or active cwd; pass `root` explicitly.",
+    };
+}
+const MAX_LINE_LEN = 160;
+function clipLine(s) {
+    if (s.length <= MAX_LINE_LEN)
+        return s;
+    return `${s.slice(0, MAX_LINE_LEN)}…[+${s.length - MAX_LINE_LEN}]`;
+}
+export function buildSearchTools(ctx) {
+    return {
+        grep: tool({
+            description: "Search file contents in the workspace using a regular expression. Honors .gitignore. Returns up to `max_results` (default 30, max 500) `{path, line, text}` hits, with a `truncated` flag when more existed. Long match lines are clipped to 160 chars. Use this for code navigation — do NOT brute-force read_file across the tree. Narrow with `glob` when you can; raise `max_results` only if the first batch truly isn't enough.",
+            inputSchema: z.object({
+                pattern: z
+                    .string()
+                    .describe("Regex pattern (Rust ripgrep dialect). Anchor and escape literal characters as needed."),
+                root: z
+                    .string()
+                    .optional()
+                    .describe("Root to search under. Defaults to workspace root, then active cwd."),
+                glob: z
+                    .array(z.string())
+                    .optional()
+                    .describe("Optional include-globs over relative paths, e.g. ['**/*.ts', 'src/**/*.tsx']."),
+                case_insensitive: z.boolean().optional(),
+                max_results: z.number().int().min(1).max(500).optional(),
+            }),
+            execute: async ({ pattern, root, glob, case_insensitive, max_results, }) => {
+                const r = resolveRoot(root, ctx);
+                if (!r.ok)
+                    return { error: r.error };
+                const safety = await checkReadableCanonical(r.path, getAiAdapter().native.canonicalize);
+                if (!safety.ok)
+                    return { error: safety.reason, root: r.path };
+                r.path = safety.canonical;
+                const cap = Math.min(max_results ?? 30, 500);
+                try {
+                    const res = await getAiAdapter().native.grep({
+                        pattern,
+                        root: r.path,
+                        glob,
+                        caseInsensitive: case_insensitive,
+                        maxResults: cap,
+                    });
+                    return {
+                        root: r.path,
+                        hits: res.hits.map((h) => ({
+                            path: h.path,
+                            rel: h.rel,
+                            line: h.line,
+                            text: clipLine(h.text),
+                        })),
+                        truncated: res.truncated,
+                        files_scanned: res.files_scanned,
+                    };
+                }
+                catch (e) {
+                    return { error: String(e), root: r.path };
+                }
+            },
+        }),
+        glob: tool({
+            description: "Find files by path pattern (gitignore-aware). Use over `list_directory` when you want all matches recursively. Patterns use globset syntax: `**/*.ts`, `src/**/test_*.py`. Returns up to `max_results` matches.",
+            inputSchema: z.object({
+                pattern: z.string().describe("Glob pattern over relative paths."),
+                root: z.string().optional(),
+                max_results: z.number().int().min(1).max(2000).optional(),
+            }),
+            execute: async ({ pattern, root, max_results }) => {
+                const r = resolveRoot(root, ctx);
+                if (!r.ok)
+                    return { error: r.error };
+                const safety = await checkReadableCanonical(r.path, getAiAdapter().native.canonicalize);
+                if (!safety.ok)
+                    return { error: safety.reason, root: r.path };
+                r.path = safety.canonical;
+                try {
+                    const res = await getAiAdapter().native.glob({
+                        pattern,
+                        root: r.path,
+                        maxResults: max_results,
+                    });
+                    return {
+                        root: r.path,
+                        hits: res.hits,
+                        truncated: res.truncated,
+                    };
+                }
+                catch (e) {
+                    return { error: String(e), root: r.path };
+                }
+            },
+        }),
+    };
+}

package/dist/tools/shell.d.ts

@@ -0,0 +1,7 @@
+import type { ToolContext } from "./context.js";
+export declare function buildShellTools(ctx: ToolContext): {
+    bash_run: import("ai").Tool<{
+        command: string;
+        timeout_secs?: number | undefined;
+    }, any>;
+};

package/dist/tools/shell.js

@@ -0,0 +1,37 @@
+import { tool } from "ai";
+import { z } from "zod";
+import { getAiAdapter } from "../config.js";
+import { checkShellCommand } from "../lib/security.js";
+const sessionShells = new Map();
+async function getSessionShell(sessionId, cwd) {
+    let p = sessionShells.get(sessionId);
+    if (p)
+        return p;
+    const newP = getAiAdapter().native.shellSessionOpen(cwd);
+    sessionShells.set(sessionId, newP);
+    return newP;
+}
+export function buildShellTools(ctx) {
+    return {
+        bash_run: tool({
+            description: "Run a shell command.",
+            inputSchema: z.object({
+                command: z.string(),
+                timeout_secs: z.number().optional(),
+            }),
+            execute: async ({ command, timeout_secs }) => {
+                const safety = checkShellCommand(command);
+                if (!safety.ok) {
+                    return { error: safety.reason };
+                }
+                const sid = ctx.getSessionId();
+                if (!sid)
+                    return { error: "no active chat session" };
+                const cwd = ctx.getCwd();
+                const shellId = await getSessionShell(sid, cwd);
+                const r = await getAiAdapter().native.shellSessionRun(shellId, command, cwd, timeout_secs ?? undefined);
+                return r;
+            },
+        }),
+    };
+}

package/dist/tools/subagent.d.ts

@@ -0,0 +1,2 @@
+import type { ToolContext } from "./context.js";
+export declare function buildSubagentTools(ctx: ToolContext): {};

package/dist/tools/subagent.js

@@ -0,0 +1,3 @@
+export function buildSubagentTools(ctx) {
+    return {};
+}

package/dist/tools/terminal.d.ts

@@ -0,0 +1,44 @@
+import type { ToolContext } from "./context.js";
+export declare function buildTerminalTools(ctx: ToolContext): {
+    readonly suggest_command: import("ai").Tool<{
+        command: string;
+        explanation?: string | undefined;
+    }, {
+        error: string;
+        command?: undefined;
+        explanation?: undefined;
+    } | {
+        command: string;
+        explanation: string | undefined;
+        error?: undefined;
+    }>;
+    readonly get_terminal_output: import("ai").Tool<{
+        lines?: number | undefined;
+    }, {
+        error: string;
+        output?: undefined;
+        note?: undefined;
+        lines_returned?: undefined;
+    } | {
+        output: string;
+        note: string;
+        error?: undefined;
+        lines_returned?: undefined;
+    } | {
+        output: string;
+        lines_returned: number;
+        error?: undefined;
+        note?: undefined;
+    }>;
+    readonly open_preview: import("ai").Tool<{
+        url: string;
+    }, {
+        error: string;
+        url: string;
+        ok?: undefined;
+    } | {
+        url: string;
+        ok: boolean;
+        error?: undefined;
+    }>;
+};

package/dist/tools/terminal.js

@@ -0,0 +1,100 @@
+import { tool } from "ai";
+import { z } from "zod";
+import { checkShellCommand } from "../lib/security.js";
+export function buildTerminalTools(ctx) {
+    return {
+        suggest_command: tool({
+            description: "Propose a single shell command. Renders a card in chat with an 'Insert' button — the command is NOT written to any terminal automatically; only the user's click inserts it at the prompt without executing. Use this when the answer IS a command.",
+            inputSchema: z.object({
+                command: z
+                    .string()
+                    .describe("The shell command. Single line, no trailing newline."),
+                explanation: z
+                    .string()
+                    .optional()
+                    .describe("Optional one-line note shown beside the command."),
+            }),
+            execute: async ({ command, explanation }) => {
+                const safety = checkShellCommand(command);
+                if (!safety.ok)
+                    return { error: safety.reason };
+                // Reject control bytes — the user inserts via click, but the rendered
+                // command must reflect exactly what will land at the prompt.
+                // biome-ignore lint/suspicious/noControlCharactersInRegex: rejecting control bytes is the entire point of this guard.
+                if (/[\n\r\x00\x1b\x07]/.test(command)) {
+                    return {
+                        error: "command must be a single line without control bytes",
+                    };
+                }
+                return { command, explanation };
+            },
+        }),
+        get_terminal_output: tool({
+            description: "Return the tail of the active terminal's scrollback. Use this when the user references 'this error', 'the last command', or you need to interpret recent terminal output. Default is 80 lines; raise it only when you genuinely need more. Returns an empty string if there is no active terminal; refuses if the terminal is in Privacy mode.",
+            inputSchema: z.object({
+                lines: z
+                    .number()
+                    .int()
+                    .min(1)
+                    .max(2000)
+                    .optional()
+                    .describe("Number of trailing lines to return. Default 80."),
+            }),
+            execute: async ({ lines }) => {
+                if (ctx.isActiveTerminalPrivate()) {
+                    return {
+                        error: "active terminal is in Privacy mode; its buffer is withheld. Ask the user to switch to a regular tab if they want you to see it.",
+                    };
+                }
+                const buffer = ctx.getTerminalContext();
+                if (!buffer)
+                    return { output: "", note: "no active terminal" };
+                const n = lines ?? 80;
+                const parts = buffer.split("\n");
+                const sliced = parts.length <= n ? buffer : parts.slice(parts.length - n).join("\n");
+                const MAX = 24_000;
+                const capped = sliced.length > MAX
+                    ? `…[truncated]…\n${sliced.slice(sliced.length - MAX)}`
+                    : sliced;
+                return { output: capped, lines_returned: Math.min(parts.length, n) };
+            },
+        }),
+        open_preview: tool({
+            description: "Open a preview tab (in-app iframe) at the given URL — restricted to localhost/loopback addresses for the local dev server. Use this after starting a dev server (e.g. `pnpm dev`, `npm run dev`) to surface the rendered page next to the terminal. To preview external sites, the user should paste the URL into the preview address bar themselves.",
+            inputSchema: z.object({
+                url: z
+                    .url()
+                    .describe("Full URL to load (e.g. http://localhost:5173). Must include scheme. Only http/https on loopback hosts are accepted."),
+            }),
+            execute: async ({ url }) => {
+                let parsed;
+                try {
+                    parsed = new URL(url);
+                }
+                catch {
+                    return { error: "invalid URL", url };
+                }
+                if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+                    return { error: "only http/https URLs are allowed", url };
+                }
+                const host = parsed.hostname;
+                const isLocal = host === "localhost" ||
+                    host === "127.0.0.1" ||
+                    host === "0.0.0.0" ||
+                    host === "[::1]" ||
+                    host === "::1" ||
+                    host.endsWith(".localhost");
+                if (!isLocal) {
+                    return {
+                        error: "open_preview is restricted to localhost URLs. Ask the user to paste the external URL into the preview address bar instead.",
+                        url,
+                    };
+                }
+                const ok = ctx.openPreview(url);
+                if (!ok)
+                    return { error: "preview surface unavailable", url };
+                return { url, ok: true };
+            },
+        }),
+    };
+}

package/dist/tools/todo.d.ts

@@ -0,0 +1,2 @@
+import type { ToolContext } from "./context.js";
+export declare function buildTodoTools(ctx: ToolContext): {};

package/dist/tools/todo.js

@@ -0,0 +1,3 @@
+export function buildTodoTools(ctx) {
+    return {};
+}