@jait/gateway 0.1.0

package/dist/tools/core/edit.js

@@ -0,0 +1,109 @@
+/**
+ * edit — Create, overwrite, or patch files.
+ *
+ * Inspired by VS Code Copilot's create_file + replace_string_in_file,
+ * unified into a single tool with an `explanation` field.
+ *
+ * Key design decisions (learned from Copilot):
+ * - `explanation` param generates first → helps LLM reason about the change
+ * - Create mode fails if file already exists with content (use patch instead)
+ * - Patch mode requires exact literal match (like Copilot replace_string)
+ * - Guidance: "read the file first before patching"
+ * - Guidance: "include at least 3 lines of context for unambiguous matching"
+ */
+import { getFs } from "./get-fs.js";
+export function createEditTool(registry) {
+    return {
+        name: "edit",
+        description: "Create a new file, overwrite an existing file, or patch (search-and-replace) part of a file.\n\n" +
+            "**To create a new file:** provide `path` and `content`. The directory is created automatically. " +
+            "Never use this to edit a file that already exists — use patch mode instead.\n\n" +
+            "**To overwrite an existing file:** provide `path` and `content`. Use this when you want to replace the " +
+            "entire file contents.\n\n" +
+            "**To patch (search-and-replace):** provide `path`, `search` (exact literal text to find), and `replace` " +
+            "(the replacement text). Each call replaces exactly ONE occurrence.\n\n" +
+            "CRITICAL for `search`: Must be the EXACT literal text from the file, including all whitespace, " +
+            "indentation, and newlines. Include at least 3 lines of context BEFORE and AFTER the target text " +
+            "to ensure an unambiguous match. If the string matches multiple locations, or doesn't match at all, " +
+            "the tool will fail.\n\n" +
+            "Always generate the `explanation` property first. Always read the file before patching.",
+        tier: "core",
+        category: "filesystem",
+        source: "builtin",
+        parameters: {
+            type: "object",
+            properties: {
+                explanation: {
+                    type: "string",
+                    description: "A short explanation of the edit being made. Generate this FIRST before the other fields.",
+                },
+                path: {
+                    type: "string",
+                    description: "The absolute or workspace-relative file path to create or edit.",
+                },
+                content: {
+                    type: "string",
+                    description: "Full file content. Use this to create a new file or overwrite an existing file entirely.",
+                },
+                search: {
+                    type: "string",
+                    description: "The exact literal text to find in the file (for patch mode). " +
+                        "MUST be the exact text including all whitespace, indentation, and newlines. " +
+                        "Include at least 3 lines of context BEFORE and AFTER the target text for unambiguous matching. " +
+                        "Must uniquely identify a single location in the file.",
+                },
+                replace: {
+                    type: "string",
+                    description: "The exact literal replacement text (for patch mode). " +
+                        "Provide the complete replacement including surrounding context lines.",
+                },
+            },
+            required: ["explanation", "path"],
+        },
+        async execute(input, context) {
+            try {
+                const fs = await getFs(registry, context, input.path);
+                // ── Patch mode: search + replace ─────────────────────────
+                if (input.search != null) {
+                    if (input.replace == null) {
+                        return { ok: false, message: "Patch mode requires both `search` and `replace`." };
+                    }
+                    const result = await fs.patch(input.path, input.search, input.replace);
+                    if (!result.matched) {
+                        return {
+                            ok: false,
+                            message: `Search string not found in ${input.path}. ` +
+                                "Ensure the search text is an exact literal match including whitespace and indentation. " +
+                                "Read the file first to get the exact text.",
+                        };
+                    }
+                    return {
+                        ok: true,
+                        message: `Patched ${input.path}: ${input.explanation}`,
+                        data: { path: input.path, mode: "patch", explanation: input.explanation },
+                    };
+                }
+                // ── Create / overwrite mode ──────────────────────────────
+                if (input.content == null) {
+                    return {
+                        ok: false,
+                        message: "Provide `content` to create/overwrite, or `search` + `replace` to patch.",
+                    };
+                }
+                await fs.write(input.path, input.content);
+                return {
+                    ok: true,
+                    message: `Wrote ${input.path} (${input.content.length} bytes): ${input.explanation}`,
+                    data: { path: input.path, mode: "write", size: input.content.length, explanation: input.explanation },
+                };
+            }
+            catch (err) {
+                return {
+                    ok: false,
+                    message: err instanceof Error ? err.message : "Edit failed",
+                };
+            }
+        },
+    };
+}
+//# sourceMappingURL=edit.js.map

package/dist/tools/core/edit.js.map

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

package/dist/tools/core/execute.d.ts

@@ -0,0 +1,36 @@
+/**
+ * execute — Run shell commands in a persistent terminal.
+ *
+ * Inspired by VS Code Copilot's run_in_terminal:
+ * - `isBackground` for long-running processes (servers, watchers)
+ * - `explanation` for human-readable display of what the command does
+ * - `goal` for short description shown in UI before the command runs
+ * - `cwd` for setting working directory
+ * - `timeout` with sensible defaults
+ *
+ * The terminal is visible to the user and persists between calls.
+ */
+import type { ToolDefinition } from "../contracts.js";
+import type { SurfaceRegistry } from "../../surfaces/registry.js";
+interface ExecuteInput {
+    /** The shell command to execute */
+    command: string;
+    /** A one-sentence description of what the command does (shown to the user before running) */
+    explanation: string;
+    /** A short description of the goal or purpose (e.g. "Install dependencies", "Start dev server") */
+    goal?: string;
+    /** Whether this starts a background process (server, watcher, build --watch).
+     *  If true, the command runs asynchronously and you won't see the output immediately.
+     *  If false (default), the command blocks until complete and returns output. */
+    isBackground?: boolean;
+    /** Working directory for the command (defaults to workspace root) */
+    cwd?: string;
+    /** Reuse a specific terminal (omit to auto-select or create) */
+    terminalId?: string;
+    /** Execution timeout in ms (default 30000). Use 0 for no timeout.
+     *  Be conservative — give enough time for the command to complete on a slow machine. */
+    timeout?: number;
+}
+export declare function createExecuteTool(registry: SurfaceRegistry): ToolDefinition<ExecuteInput>;
+export {};
+//# sourceMappingURL=execute.d.ts.map

package/dist/tools/core/execute.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute.d.ts","sourceRoot":"","sources":["../../../src/tools/core/execute.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,cAAc,EAA2B,MAAM,iBAAiB,CAAC;AAC/E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAGlE,UAAU,YAAY;IACpB,mCAAmC;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,6FAA6F;IAC7F,WAAW,EAAE,MAAM,CAAC;IACpB,mGAAmG;IACnG,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;oFAEgF;IAChF,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,qEAAqE;IACrE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;4FACwF;IACxF,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,eAAe,GAAG,cAAc,CAAC,YAAY,CAAC,CAyEzF"}

package/dist/tools/core/execute.js

@@ -0,0 +1,81 @@
+/**
+ * execute — Run shell commands in a persistent terminal.
+ *
+ * Inspired by VS Code Copilot's run_in_terminal:
+ * - `isBackground` for long-running processes (servers, watchers)
+ * - `explanation` for human-readable display of what the command does
+ * - `goal` for short description shown in UI before the command runs
+ * - `cwd` for setting working directory
+ * - `timeout` with sensible defaults
+ *
+ * The terminal is visible to the user and persists between calls.
+ */
+import { createTerminalRunTool } from "../terminal-tools.js";
+export function createExecuteTool(registry) {
+    // Delegate to the existing terminal.run implementation
+    const inner = createTerminalRunTool(registry);
+    return {
+        name: "execute",
+        description: "Run a shell command in a persistent terminal and return the output.\n\n" +
+            "The terminal is visible to the user and stays alive between calls. " +
+            "Use PowerShell syntax on Windows. Multi-line scripts, pipes, and complex syntax all work.\n\n" +
+            "Set `isBackground: true` for long-running processes (servers, watchers, build in watch mode). " +
+            "Background commands run asynchronously — you won't see output immediately but the process keeps running.\n\n" +
+            "Use this for: running builds, installing packages, git operations, starting servers, " +
+            "checking processes, running tests, or any shell task.\n\n" +
+            "When executing non-trivial commands, explain their purpose so the user understands what's happening. " +
+            "Prefer using `;` to chain commands on one line. Use `timeout: 0` for commands that may take a long time.",
+        tier: "core",
+        category: "terminal",
+        source: "builtin",
+        parameters: {
+            type: "object",
+            properties: {
+                command: {
+                    type: "string",
+                    description: "The shell command to execute.",
+                },
+                explanation: {
+                    type: "string",
+                    description: "A one-sentence description of what the command does. Shown to the user before the command runs.",
+                },
+                goal: {
+                    type: "string",
+                    description: 'A short description of the goal (e.g., "Install dependencies", "Start development server").',
+                },
+                isBackground: {
+                    type: "boolean",
+                    description: "Whether this starts a background process. " +
+                        "If true, runs asynchronously (e.g. servers, watchers). " +
+                        "If false (default), blocks until complete and returns output.",
+                },
+                cwd: {
+                    type: "string",
+                    description: "Working directory for the command. Defaults to workspace root.",
+                },
+                terminalId: {
+                    type: "string",
+                    description: "Reuse a specific terminal by ID (omit to auto-select or create).",
+                },
+                timeout: {
+                    type: "number",
+                    description: "Execution timeout in milliseconds (default 30000). " +
+                        "Use 0 for no timeout. Be conservative — give enough time for slow machines.",
+                },
+            },
+            required: ["command", "explanation"],
+        },
+        async execute(input, context) {
+            // Forward all params to the inner terminal.run tool
+            return inner.execute({
+                command: input.command,
+                terminalId: input.terminalId,
+                timeout: input.timeout,
+                cwd: input.cwd,
+                // Pass background flag if the inner tool supports it
+                ...(input.isBackground != null ? { isBackground: input.isBackground } : {}),
+            }, context);
+        },
+    };
+}
+//# sourceMappingURL=execute.js.map

package/dist/tools/core/execute.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute.js","sourceRoot":"","sources":["../../../src/tools/core/execute.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAsB7D,MAAM,UAAU,iBAAiB,CAAC,QAAyB;IACzD,uDAAuD;IACvD,MAAM,KAAK,GAAG,qBAAqB,CAAC,QAAQ,CAAC,CAAC;IAE9C,OAAO;QACL,IAAI,EAAE,SAAS;QACf,WAAW,EACT,yEAAyE;YACzE,qEAAqE;YACrE,+FAA+F;YAC/F,gGAAgG;YAChG,8GAA8G;YAC9G,uFAAuF;YACvF,2DAA2D;YAC3D,uGAAuG;YACvG,0GAA0G;QAC5G,IAAI,EAAE,MAAM;QACZ,QAAQ,EAAE,UAAU;QACpB,MAAM,EAAE,SAAS;QACjB,UAAU,EAAE;YACV,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,OAAO,EAAE;oBACP,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,+BAA+B;iBAC7C;gBACD,WAAW,EAAE;oBACX,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,iGAAiG;iBAC/G;gBACD,IAAI,EAAE;oBACJ,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,6FAA6F;iBAC3G;gBACD,YAAY,EAAE;oBACZ,IAAI,EAAE,SAAS;oBACf,WAAW,EACT,4CAA4C;wBAC5C,yDAAyD;wBACzD,+DAA+D;iBAClE;gBACD,GAAG,EAAE;oBACH,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,gEAAgE;iBAC9E;gBACD,UAAU,EAAE;oBACV,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,kEAAkE;iBAChF;gBACD,OAAO,EAAE;oBACP,IAAI,EAAE,QAAQ;oBACd,WAAW,EACT,qDAAqD;wBACrD,6EAA6E;iBAChF;aACF;YACD,QAAQ,EAAE,CAAC,SAAS,EAAE,aAAa,CAAC;SACrC;QACD,KAAK,CAAC,OAAO,CAAC,KAAmB,EAAE,OAAoB;YACrD,oDAAoD;YACpD,OAAO,KAAK,CAAC,OAAO,CAClB;gBACE,OAAO,EAAE,KAAK,CAAC,OAAO;gBACtB,UAAU,EAAE,KAAK,CAAC,UAAU;gBAC5B,OAAO,EAAE,KAAK,CAAC,OAAO;gBACtB,GAAG,EAAE,KAAK,CAAC,GAAG;gBACd,qDAAqD;gBACrD,GAAG,CAAC,KAAK,CAAC,YAAY,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,KAAK,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACrE,EACR,OAAO,CACR,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/tools/core/get-fs.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Shared helper — resolve the FileSystemSurface for the current session.
+ *
+ * Priority:
+ * 1. If `targetPath` is absolute and outside the current workspace boundary,
+ *    find or create a surface scoped to contain that path.
+ * 2. Look for an existing surface with the conventional ID `fs-{sessionId}`
+ *    that is running (the auto-created surface for the session).
+ * 3. Look for *any* running filesystem surface belonging to the session
+ *    (e.g. one started via `surfaces.start` with a custom workspace root).
+ * 4. If nothing exists, auto-start one with `context.workspaceRoot`.
+ *
+ * This ensures that when the user asks to read/edit files anywhere on their
+ * local filesystem, the agent can access them without "escapes workspace
+ * boundary" errors — while still maintaining PathGuard isolation per surface.
+ */
+import type { ToolContext } from "../contracts.js";
+import type { SurfaceRegistry } from "../../surfaces/registry.js";
+import { FileSystemSurface } from "../../surfaces/filesystem.js";
+export declare function getFs(registry: SurfaceRegistry, context: ToolContext, targetPath?: string): Promise<FileSystemSurface>;
+/**
+ * Resolve the effective workspace root for a session.
+ *
+ * Prefers the most specific (deepest) workspace root among all running
+ * filesystem surfaces for this session — avoids returning a broad drive root
+ * when a more specific workspace surface exists.
+ * Falls back to `process.cwd()`.
+ */
+export declare function resolveWorkspaceRoot(registry: SurfaceRegistry, sessionId: string, 
+/** Optional fallback from session record before falling back to process.cwd() */
+sessionWorkspacePath?: string | null): string;
+//# sourceMappingURL=get-fs.d.ts.map

package/dist/tools/core/get-fs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-fs.d.ts","sourceRoot":"","sources":["../../../src/tools/core/get-fs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AA8CjE,wBAAsB,KAAK,CACzB,QAAQ,EAAE,eAAe,EACzB,OAAO,EAAE,WAAW,EACpB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,iBAAiB,CAAC,CA8D5B;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,eAAe,EACzB,SAAS,EAAE,MAAM;AACjB,iFAAiF;AACjF,oBAAoB,CAAC,EAAE,MAAM,GAAG,IAAI,GACnC,MAAM,CAcR"}

package/dist/tools/core/get-fs.js

@@ -0,0 +1,143 @@
+/**
+ * Shared helper — resolve the FileSystemSurface for the current session.
+ *
+ * Priority:
+ * 1. If `targetPath` is absolute and outside the current workspace boundary,
+ *    find or create a surface scoped to contain that path.
+ * 2. Look for an existing surface with the conventional ID `fs-{sessionId}`
+ *    that is running (the auto-created surface for the session).
+ * 3. Look for *any* running filesystem surface belonging to the session
+ *    (e.g. one started via `surfaces.start` with a custom workspace root).
+ * 4. If nothing exists, auto-start one with `context.workspaceRoot`.
+ *
+ * This ensures that when the user asks to read/edit files anywhere on their
+ * local filesystem, the agent can access them without "escapes workspace
+ * boundary" errors — while still maintaining PathGuard isolation per surface.
+ */
+import { resolve, isAbsolute, dirname } from "node:path";
+import { stat } from "node:fs/promises";
+import { FileSystemSurface } from "../../surfaces/filesystem.js";
+/**
+ * Given a `targetPath`, determine the correct workspace root.
+ * If the path is a directory, use it directly.
+ * If the path is a file, use its parent directory.
+ * Falls back to the path itself if stat fails (e.g. doesn't exist yet).
+ */
+async function deriveWorkspaceRoot(targetPath) {
+    const abs = resolve(targetPath);
+    try {
+        const info = await stat(abs);
+        return info.isDirectory() ? abs : dirname(abs);
+    }
+    catch {
+        // Path doesn't exist yet — use the parent directory
+        return dirname(abs);
+    }
+}
+/**
+ * Check if `surface` can serve `targetPath` (i.e. the path is within
+ * the surface's workspace boundary).
+ */
+function surfaceCovers(surface, targetPath) {
+    return surface.isPathAllowed(targetPath);
+}
+/**
+ * Among multiple surfaces that cover a path, prefer the most specific one
+ * (deepest workspace root).
+ */
+function pickMostSpecific(surfaces, targetPath) {
+    let best = null;
+    let bestLen = -1;
+    for (const s of surfaces) {
+        if (!surfaceCovers(s, targetPath))
+            continue;
+        const root = s.snapshot().metadata?.workspaceRoot;
+        const len = root?.length ?? 0;
+        if (len > bestLen) {
+            best = s;
+            bestLen = len;
+        }
+    }
+    return best;
+}
+export async function getFs(registry, context, targetPath) {
+    const absTarget = targetPath ? resolve(context.workspaceRoot, targetPath) : undefined;
+    // ── If target is absolute and we already have a surface that covers it, use it ──
+    if (absTarget) {
+        // Collect all running FS surfaces for this session
+        const candidates = [];
+        const fsId = `fs-${context.sessionId}`;
+        const conventional = registry.getSurface(fsId);
+        if (conventional?.state === "running")
+            candidates.push(conventional);
+        for (const s of registry.getBySession(context.sessionId)) {
+            if (s instanceof FileSystemSurface && s.state === "running" && s !== conventional) {
+                candidates.push(s);
+            }
+        }
+        // Pick the most specific surface that covers this path
+        const best = pickMostSpecific(candidates, absTarget);
+        if (best)
+            return best;
+        // No existing surface covers this path — create one scoped to the target
+        if (isAbsolute(targetPath)) {
+            const newRoot = await deriveWorkspaceRoot(absTarget);
+            const safeName = newRoot.replace(/[:\\\/]/g, "_").replace(/_+$/, "").toLowerCase();
+            const surfaceId = `fs-${context.sessionId}-${safeName}`;
+            const existing = registry.getSurface(surfaceId);
+            if (existing?.state === "running")
+                return existing;
+            const started = await registry.startSurface("filesystem", surfaceId, {
+                sessionId: context.sessionId,
+                workspaceRoot: newRoot,
+            });
+            return started;
+        }
+    }
+    // ── Default: find or create the conventional session surface ──
+    // 1. Conventional per-session ID
+    const fsId = `fs-${context.sessionId}`;
+    const conventional = registry.getSurface(fsId);
+    if (conventional && conventional.state === "running")
+        return conventional;
+    // 2. Any running filesystem surface for this session
+    const sessionSurfaces = registry.getBySession(context.sessionId);
+    for (const s of sessionSurfaces) {
+        if (s instanceof FileSystemSurface &&
+            s.state === "running") {
+            return s;
+        }
+    }
+    // 3. Nothing found — auto-start one
+    const started = await registry.startSurface("filesystem", fsId, {
+        sessionId: context.sessionId,
+        workspaceRoot: context.workspaceRoot,
+    });
+    return started;
+}
+/**
+ * Resolve the effective workspace root for a session.
+ *
+ * Prefers the most specific (deepest) workspace root among all running
+ * filesystem surfaces for this session — avoids returning a broad drive root
+ * when a more specific workspace surface exists.
+ * Falls back to `process.cwd()`.
+ */
+export function resolveWorkspaceRoot(registry, sessionId, 
+/** Optional fallback from session record before falling back to process.cwd() */
+sessionWorkspacePath) {
+    let best = null;
+    let bestLen = -1;
+    for (const s of registry.getBySession(sessionId)) {
+        if (s instanceof FileSystemSurface && s.state === "running") {
+            const root = s.snapshot().metadata
+                ?.workspaceRoot;
+            if (root && root.length > bestLen) {
+                best = root;
+                bestLen = root.length;
+            }
+        }
+    }
+    return best ?? sessionWorkspacePath?.trim() ?? process.cwd();
+}
+//# sourceMappingURL=get-fs.js.map

package/dist/tools/core/get-fs.js.map

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

package/dist/tools/core/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Core tools — The 8 essential tools that form the agent's primary toolkit.
+ *
+ * Design inspired by VS Code Copilot Chat's tool system, adapted for
+ * Jait's gateway-centric architecture:
+ *
+ * | Tool    | Copilot Equivalent(s)              | Category    |
+ * |---------|------------------------------------|-------------|
+ * | read    | read_file + list_dir               | filesystem  |
+ * | edit    | create_file + replace_string       | filesystem  |
+ * | execute | run_in_terminal                    | terminal    |
+ * | search  | grep_search + file_search          | filesystem  |
+ * | web     | fetch_webpage (+ web search)       | web         |
+ * | agent   | runSubagent + search_subagent      | agent       |
+ * | todo    | manage_todo_list                   | meta        |
+ * | jait    | memory + (no equiv for cron/status) | gateway    |
+ */
+export { createReadTool } from "./read.js";
+export { createEditTool } from "./edit.js";
+export { createExecuteTool } from "./execute.js";
+export { createSearchTool } from "./search.js";
+export { createWebTool } from "./web.js";
+export { createAgentTool } from "./agent.js";
+export { createTodoTool, getSessionTodos, clearSessionTodos, type TodoItem } from "./todo.js";
+export { createJaitTool, type JaitToolDeps } from "./jait.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/core/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/tools/core/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,iBAAiB,EAAE,KAAK,QAAQ,EAAE,MAAM,WAAW,CAAC;AAC9F,OAAO,EAAE,cAAc,EAAE,KAAK,YAAY,EAAE,MAAM,WAAW,CAAC"}

package/dist/tools/core/index.js

@@ -0,0 +1,26 @@
+/**
+ * Core tools — The 8 essential tools that form the agent's primary toolkit.
+ *
+ * Design inspired by VS Code Copilot Chat's tool system, adapted for
+ * Jait's gateway-centric architecture:
+ *
+ * | Tool    | Copilot Equivalent(s)              | Category    |
+ * |---------|------------------------------------|-------------|
+ * | read    | read_file + list_dir               | filesystem  |
+ * | edit    | create_file + replace_string       | filesystem  |
+ * | execute | run_in_terminal                    | terminal    |
+ * | search  | grep_search + file_search          | filesystem  |
+ * | web     | fetch_webpage (+ web search)       | web         |
+ * | agent   | runSubagent + search_subagent      | agent       |
+ * | todo    | manage_todo_list                   | meta        |
+ * | jait    | memory + (no equiv for cron/status) | gateway    |
+ */
+export { createReadTool } from "./read.js";
+export { createEditTool } from "./edit.js";
+export { createExecuteTool } from "./execute.js";
+export { createSearchTool } from "./search.js";
+export { createWebTool } from "./web.js";
+export { createAgentTool } from "./agent.js";
+export { createTodoTool, getSessionTodos, clearSessionTodos } from "./todo.js";
+export { createJaitTool } from "./jait.js";
+//# sourceMappingURL=index.js.map

package/dist/tools/core/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/tools/core/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,iBAAiB,EAAiB,MAAM,WAAW,CAAC;AAC9F,OAAO,EAAE,cAAc,EAAqB,MAAM,WAAW,CAAC"}

package/dist/tools/core/jait.d.ts

@@ -0,0 +1,60 @@
+/**
+ * jait — Platform meta-tool for Jait-specific capabilities.
+ *
+ * Combines: memory management, cron/scheduler, network scanning,
+ * and gateway status into a single tool with an `action` dispatcher.
+ *
+ * This keeps the core tool count at 8 while still exposing
+ * platform-specific features that don't fit the generic tools.
+ */
+import type { ToolDefinition } from "../contracts.js";
+import type { SchedulerService } from "../../scheduler/service.js";
+import type { MemoryService } from "../../memory/contracts.js";
+import type { SessionService } from "../../services/sessions.js";
+import type { SurfaceRegistry } from "../../surfaces/registry.js";
+import type { WsControlPlane } from "../../ws.js";
+import type { HookBus } from "../../scheduler/hooks.js";
+export interface JaitToolDeps {
+    memoryService?: MemoryService;
+    scheduler?: SchedulerService;
+    sessionService?: SessionService;
+    surfaceRegistry?: SurfaceRegistry;
+    ws?: WsControlPlane;
+    startedAt?: number;
+    hooks?: HookBus;
+}
+interface JaitInput {
+    /** The action to perform */
+    action: string;
+    /** Memory content to save */
+    content?: string;
+    /** Memory scope: workspace, project, or contact */
+    scope?: string;
+    /** Search query for memory.search */
+    query?: string;
+    /** Memory ID (for forget) */
+    memoryId?: string;
+    /** Source type for memory save */
+    sourceType?: string;
+    /** Source ID for memory save */
+    sourceId?: string;
+    /** TTL in seconds for memory expiry */
+    ttlSeconds?: number;
+    /** Max results for memory search */
+    limit?: number;
+    /** Cron job name */
+    name?: string;
+    /** Cron expression */
+    cron?: string;
+    /** Tool name to execute on schedule */
+    toolName?: string;
+    /** Tool input arguments */
+    input?: Record<string, unknown>;
+    /** Cron job ID (for update/remove) */
+    jobId?: string;
+    /** Enable/disable flag for cron update */
+    enabled?: boolean;
+}
+export declare function createJaitTool(deps: JaitToolDeps): ToolDefinition<JaitInput>;
+export {};
+//# sourceMappingURL=jait.d.ts.map

package/dist/tools/core/jait.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jait.d.ts","sourceRoot":"","sources":["../../../src/tools/core/jait.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,cAAc,EAA2B,MAAM,iBAAiB,CAAC;AAC/E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AACnE,OAAO,KAAK,EAAE,aAAa,EAAe,MAAM,2BAA2B,CAAC;AAC5E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AAExD,MAAM,WAAW,YAAY;IAC3B,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,SAAS,CAAC,EAAE,gBAAgB,CAAC;IAC7B,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,EAAE,CAAC,EAAE,cAAc,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,UAAU,SAAS;IACjB,4BAA4B;IAC5B,MAAM,EAAE,MAAM,CAAC;IAGf,6BAA6B;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mDAAmD;IACnD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6BAA6B;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kCAAkC;IAClC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gCAAgC;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uCAAuC;IACvC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oCAAoC;IACpC,KAAK,CAAC,EAAE,MAAM,CAAC;IAGf,oBAAoB;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sBAAsB;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2BAA2B;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,sCAAsC;IACtC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,YAAY,GAAG,cAAc,CAAC,SAAS,CAAC,CAwQ5E"}