@primo-ai/tools 0.1.3 → 0.1.5

package/dist/calculator.d.ts

@@ -0,0 +1,7 @@
+import type { Tool } from '@primo-ai/sdk';
+export declare const calculatorTool: Tool<{
+    expression: string;
+}, {
+    result: number;
+    expression: string;
+}>;

package/dist/calculator.js

@@ -0,0 +1,30 @@
+import { z } from 'zod';
+export const calculatorTool = {
+    name: 'calculator',
+    description: 'Evaluate a mathematical expression. Supports +, -, *, /, **, %, parentheses, and Math functions.',
+    inputSchema: z.object({
+        expression: z
+            .string()
+            .describe('Math expression (e.g. "2 + 3 * 4", "Math.sqrt(144)", "3.14 * 10 ** 2")'),
+    }),
+    requireApproval: false,
+    async execute(input) {
+        const { expression } = input;
+        const sanitized = expression.replace(/\s+/g, ' ').trim();
+        if (/[^0-9+\-*/().%\s^,a-zA-Z.]/.test(sanitized.replace(/Math\.\w+/g, ''))) {
+            throw new Error(`Disallowed characters in expression: "${expression}"`);
+        }
+        const fn = new Function(`"use strict"; return (${sanitized});`);
+        const result = fn();
+        if (typeof result !== 'number' || !Number.isFinite(result)) {
+            throw new Error(`Expression did not evaluate to a finite number: ${result}`);
+        }
+        return { result, expression };
+    },
+    renderCall(input) {
+        return `calc: ${input.expression}`;
+    },
+    renderResult(output) {
+        return `${output.expression} = ${output.result}`;
+    },
+};

package/dist/datetime.d.ts

@@ -0,0 +1,10 @@
+import type { Tool } from '@primo-ai/sdk';
+export declare const datetimeTool: Tool<{
+    format?: string;
+    timezone?: string;
+}, {
+    iso: string;
+    formatted: string;
+    timezone: string;
+    unix: number;
+}>;

package/dist/datetime.js

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+export const datetimeTool = {
+    name: 'datetime',
+    description: 'Get the current date and time. Supports timezone and format options.',
+    inputSchema: z.object({
+        format: z
+            .enum(['iso', 'locale', 'unix', 'date', 'time'])
+            .optional()
+            .default('iso')
+            .describe('Output format'),
+        timezone: z
+            .string()
+            .optional()
+            .describe('IANA timezone (e.g. "Asia/Shanghai", "America/New_York")'),
+    }),
+    requireApproval: false,
+    async execute(input) {
+        const { format = 'iso', timezone } = input;
+        const now = new Date();
+        const tz = timezone ?? Intl.DateTimeFormat().resolvedOptions().timeZone;
+        const formatted = format === 'iso'
+            ? now.toISOString()
+            : format === 'unix'
+                ? String(Math.floor(now.getTime() / 1000))
+                : format === 'date'
+                    ? now.toLocaleDateString('en-US', { timeZone: tz })
+                    : format === 'time'
+                        ? now.toLocaleTimeString('en-US', { timeZone: tz })
+                        : now.toLocaleString('en-US', { timeZone: tz });
+        return {
+            iso: now.toISOString(),
+            formatted,
+            timezone: tz,
+            unix: Math.floor(now.getTime() / 1000),
+        };
+    },
+    renderCall(input) {
+        return `datetime (${input.timezone ?? 'local'}, ${input.format ?? 'iso'})`;
+    },
+    renderResult(output) {
+        return output.formatted;
+    },
+};

package/dist/file-edit.d.ts

@@ -0,0 +1,10 @@
+import type { Tool } from '@primo-ai/sdk';
+export declare const fileEditTool: Tool<{
+    path: string;
+    oldString: string;
+    newString: string;
+    replaceAll?: boolean;
+}, {
+    path: string;
+    replacements: number;
+}>;

package/dist/file-edit.js

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+export const fileEditTool = {
+    name: 'fileEdit',
+    description: 'Perform exact string replacement in a file. Set replaceAll to replace all occurrences.',
+    inputSchema: z.object({
+        path: z.string().describe('Absolute file path'),
+        oldString: z.string().describe('Exact string to find'),
+        newString: z.string().describe('Replacement string'),
+        replaceAll: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe('Replace all occurrences'),
+    }),
+    requireApproval: true,
+    async execute(input) {
+        const fs = await import('node:fs/promises');
+        const { path, oldString, newString, replaceAll = false } = input;
+        const content = await fs.readFile(path, 'utf-8');
+        if (!content.includes(oldString)) {
+            throw new Error(`String not found in ${path}`);
+        }
+        if (!replaceAll && content.split(oldString).length - 1 > 1) {
+            throw new Error(`Multiple matches found in ${path}. Use replaceAll: true or provide more context.`);
+        }
+        const updated = replaceAll
+            ? content.replaceAll(oldString, newString)
+            : content.replace(oldString, newString);
+        await fs.writeFile(path, updated, 'utf-8');
+        const replacements = replaceAll
+            ? content.split(oldString).length - 1
+            : 1;
+        return { path, replacements };
+    },
+    renderCall(input) {
+        return `edit ${input.path}: "${input.oldString.slice(0, 40)}..." → "${input.newString.slice(0, 40)}..."`;
+    },
+    renderResult(output) {
+        return `${output.path} (${output.replacements} replacement(s))`;
+    },
+};

package/dist/file-read.d.ts

@@ -0,0 +1,11 @@
+import type { Tool } from '@primo-ai/sdk';
+export declare const fileReadTool: Tool<{
+    path: string;
+    encoding?: string;
+    offset?: number;
+    limit?: number;
+}, {
+    content: string;
+    lines: number;
+    path: string;
+}>;

package/dist/file-read.js

@@ -0,0 +1,39 @@
+import { z } from 'zod';
+export const fileReadTool = {
+    name: 'fileRead',
+    description: 'Read file contents from the local filesystem. Supports line range via offset/limit.',
+    inputSchema: z.object({
+        path: z.string().describe('Absolute file path'),
+        encoding: z
+            .enum(['utf-8', 'ascii', 'base64', 'hex', 'latin1'])
+            .optional()
+            .default('utf-8')
+            .describe('File encoding'),
+        offset: z.number().optional().describe('Start line (1-indexed)'),
+        limit: z.number().optional().describe('Max lines to read'),
+    }),
+    requireApproval: false,
+    async execute(input) {
+        const fs = await import('node:fs/promises');
+        const { path, encoding = 'utf-8', offset, limit } = input;
+        const raw = await fs.readFile(path, { encoding: encoding });
+        if (offset == null && limit == null) {
+            const lines = raw.split('\n').length;
+            return { content: raw, lines, path };
+        }
+        const allLines = raw.split('\n');
+        const start = (offset ?? 1) - 1;
+        const end = limit != null ? start + limit : allLines.length;
+        const sliced = allLines.slice(start, end);
+        const numbered = sliced
+            .map((line, i) => `${start + i + 1}\t${line}`)
+            .join('\n');
+        return { content: numbered, lines: allLines.length, path };
+    },
+    renderCall(input) {
+        return `read ${input.path}`;
+    },
+    renderResult(output) {
+        return `[${output.path}] ${output.lines} lines`;
+    },
+};

package/dist/file-write.d.ts

@@ -0,0 +1,10 @@
+import type { Tool } from '@primo-ai/sdk';
+export declare const fileWriteTool: Tool<{
+    path: string;
+    content: string;
+    encoding?: string;
+    append?: boolean;
+}, {
+    path: string;
+    bytes: number;
+}>;

package/dist/file-write.js

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+export const fileWriteTool = {
+    name: 'fileWrite',
+    description: 'Write content to a file on the local filesystem. Creates parent directories if needed.',
+    inputSchema: z.object({
+        path: z.string().describe('Absolute file path'),
+        content: z.string().describe('Content to write'),
+        encoding: z
+            .enum(['utf-8', 'ascii', 'base64', 'hex', 'latin1'])
+            .optional()
+            .default('utf-8')
+            .describe('File encoding'),
+        append: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe('Append to file instead of overwriting'),
+    }),
+    requireApproval: true,
+    async execute(input) {
+        const fs = await import('node:fs/promises');
+        const pathModule = await import('node:path');
+        const { path, content, encoding = 'utf-8', append = false } = input;
+        await fs.mkdir(pathModule.dirname(path), { recursive: true });
+        const flag = append ? 'a' : 'w';
+        await fs.writeFile(path, content, { encoding: encoding, flag });
+        const bytes = Buffer.byteLength(content, encoding);
+        return { path, bytes };
+    },
+    renderCall(input) {
+        return `${input.append ? 'append' : 'write'} ${input.path} (${input.content.length} chars)`;
+    },
+    renderResult(output) {
+        return `${output.path} (${output.bytes} bytes)`;
+    },
+};

package/dist/glob.d.ts

@@ -0,0 +1,8 @@
+import type { Tool } from '@primo-ai/sdk';
+export declare const globTool: Tool<{
+    pattern: string;
+    path?: string;
+}, {
+    files: string[];
+    count: number;
+}>;

package/dist/glob.js

@@ -0,0 +1,25 @@
+import { z } from 'zod';
+export const globTool = {
+    name: 'glob',
+    description: 'Find files matching a glob pattern. Returns file paths sorted by modification time.',
+    inputSchema: z.object({
+        pattern: z.string().describe('Glob pattern (e.g. "**/*.ts", "src/**/*.js")'),
+        path: z.string().optional().describe('Base directory to search in'),
+    }),
+    requireApproval: false,
+    async execute(input) {
+        const { glob } = await import('node:fs/promises');
+        const { pattern, path: cwd } = input;
+        const files = [];
+        for await (const entry of glob(pattern, { cwd })) {
+            files.push(entry);
+        }
+        return { files, count: files.length };
+    },
+    renderCall(input) {
+        return `glob ${input.pattern}`;
+    },
+    renderResult(output) {
+        return `${output.count} files matched`;
+    },
+};

package/dist/grep.d.ts

@@ -0,0 +1,14 @@
+import type { Tool } from '@primo-ai/sdk';
+export declare const grepTool: Tool<{
+    pattern: string;
+    path?: string;
+    include?: string;
+    maxResults?: number;
+}, {
+    matches: {
+        file: string;
+        line: number;
+        text: string;
+    }[];
+    count: number;
+}>;

package/dist/grep.js

@@ -0,0 +1,70 @@
+import { z } from 'zod';
+export const grepTool = {
+    name: 'grep',
+    description: 'Search file contents by regex pattern. Returns matching lines with file paths and line numbers.',
+    inputSchema: z.object({
+        pattern: z.string().describe('Regex pattern to search for'),
+        path: z.string().optional().describe('Directory to search in'),
+        include: z.string().optional().describe('File glob filter (e.g. "*.ts")'),
+        maxResults: z.number().optional().default(100).describe('Max results'),
+    }),
+    requireApproval: false,
+    async execute(input) {
+        const { readFile, readdir } = await import('node:fs/promises');
+        const { join, relative } = await import('node:path');
+        const { pattern, path: cwd = '.', include, maxResults = 100 } = input;
+        const regex = new RegExp(pattern, 'i');
+        const matches = [];
+        const includeRegex = include
+            ? globToRegex(include)
+            : null;
+        async function walk(dir) {
+            if (matches.length >= maxResults)
+                return;
+            const entries = await readdir(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (matches.length >= maxResults)
+                    return;
+                if (entry.name.startsWith('.') || entry.name === 'node_modules')
+                    continue;
+                const full = join(dir, entry.name);
+                if (entry.isDirectory()) {
+                    await walk(full);
+                }
+                else if (entry.isFile()) {
+                    if (includeRegex && !includeRegex.test(entry.name))
+                        continue;
+                    try {
+                        const content = await readFile(full, 'utf-8');
+                        const lines = content.split('\n');
+                        for (let i = 0; i < lines.length; i++) {
+                            if (matches.length >= maxResults)
+                                return;
+                            if (regex.test(lines[i])) {
+                                matches.push({ file: relative(cwd, full), line: i + 1, text: lines[i].trim() });
+                            }
+                        }
+                    }
+                    catch {
+                        // skip binary / unreadable files
+                    }
+                }
+            }
+        }
+        await walk(cwd);
+        return { matches, count: matches.length };
+    },
+    renderCall(input) {
+        return `grep "${input.pattern}"`;
+    },
+    renderResult(output) {
+        return `${output.count} matches`;
+    },
+};
+function globToRegex(glob) {
+    const escaped = glob
+        .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+        .replace(/\*/g, '.*')
+        .replace(/\?/g, '.');
+    return new RegExp(`^${escaped}$`);
+}

package/dist/http.d.ts

@@ -0,0 +1,11 @@
+import type { Tool } from '@primo-ai/sdk';
+export declare const httpTool: Tool<{
+    url: string;
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+}, {
+    status: number;
+    headers: Record<string, string>;
+    body: string;
+}>;

package/dist/http.js

@@ -0,0 +1,49 @@
+import { z } from 'zod';
+export const httpTool = {
+    name: 'http',
+    description: 'Make HTTP requests. Supports GET, POST, PUT, PATCH, DELETE. Returns status, headers, and body.',
+    inputSchema: z.object({
+        url: z.string().describe('The URL to request'),
+        method: z
+            .enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE'])
+            .optional()
+            .default('GET')
+            .describe('HTTP method'),
+        headers: z
+            .record(z.string(), z.string())
+            .optional()
+            .describe('Request headers'),
+        body: z.string().optional().describe('Request body (for POST/PUT/PATCH)'),
+    }),
+    outputSchema: z.object({
+        status: z.number(),
+        headers: z.record(z.string(), z.string()),
+        body: z.string(),
+    }),
+    requireApproval: false,
+    async execute(input) {
+        const { url, method = 'GET', headers = {}, body } = input;
+        const reqHeaders = new Headers();
+        reqHeaders.set('User-Agent', 'AgentForge/1.0');
+        for (const [k, v] of Object.entries(headers)) {
+            reqHeaders.set(k, v);
+        }
+        const res = await fetch(url, {
+            method,
+            headers: reqHeaders,
+            body: ['GET', 'DELETE'].includes(method) ? undefined : body,
+        });
+        const resHeaders = {};
+        res.headers.forEach((v, k) => {
+            resHeaders[k] = v;
+        });
+        const resBody = await res.text();
+        return { status: res.status, headers: resHeaders, body: resBody };
+    },
+    renderCall(input) {
+        return `${input.method ?? 'GET'} ${input.url}`;
+    },
+    renderResult(output) {
+        return `[${output.status}] ${output.body.slice(0, 200)}`;
+    },
+};

package/dist/index.d.ts

@@ -1 +1,11 @@
 export { echoTool } from './echo.js';
+export { httpTool } from './http.js';
+export { fileReadTool } from './file-read.js';
+export { fileWriteTool } from './file-write.js';
+export { fileEditTool } from './file-edit.js';
+export { globTool } from './glob.js';
+export { grepTool } from './grep.js';
+export { shellTool } from './shell.js';
+export { calculatorTool } from './calculator.js';
+export { datetimeTool } from './datetime.js';
+export { jsonTool } from './json.js';

package/dist/index.js

@@ -1,2 +1,12 @@
 // @primo-ai/tools — Built-in tools
 export { echoTool } from './echo.js';
+export { httpTool } from './http.js';
+export { fileReadTool } from './file-read.js';
+export { fileWriteTool } from './file-write.js';
+export { fileEditTool } from './file-edit.js';
+export { globTool } from './glob.js';
+export { grepTool } from './grep.js';
+export { shellTool } from './shell.js';
+export { calculatorTool } from './calculator.js';
+export { datetimeTool } from './datetime.js';
+export { jsonTool } from './json.js';

package/dist/json.d.ts

@@ -0,0 +1,9 @@
+import type { Tool } from '@primo-ai/sdk';
+export declare const jsonTool: Tool<{
+    operation: 'parse' | 'stringify' | 'query';
+    data: string;
+    path?: string;
+    indent?: number;
+}, {
+    result: string;
+}>;

package/dist/json.js

@@ -0,0 +1,49 @@
+import { z } from 'zod';
+export const jsonTool = {
+    name: 'json',
+    description: 'Parse, stringify, or query JSON data. Query uses dot-notation paths (e.g. "users.0.name").',
+    inputSchema: z.object({
+        operation: z
+            .enum(['parse', 'stringify', 'query'])
+            .describe('Operation to perform'),
+        data: z.string().describe('JSON string or value to process'),
+        path: z
+            .string()
+            .optional()
+            .describe('Dot-notation path for query (e.g. "users.0.name")'),
+        indent: z.number().optional().default(2).describe('Indentation for stringify'),
+    }),
+    requireApproval: false,
+    async execute(input) {
+        const { operation, data, path, indent = 2 } = input;
+        switch (operation) {
+            case 'parse': {
+                const parsed = JSON.parse(data);
+                return { result: JSON.stringify(parsed, null, indent) };
+            }
+            case 'stringify': {
+                const parsed = JSON.parse(data);
+                return { result: JSON.stringify(parsed, null, indent) };
+            }
+            case 'query': {
+                if (!path)
+                    throw new Error('path is required for query operation');
+                const parsed = JSON.parse(data);
+                const result = path.split('.').reduce((obj, key) => {
+                    if (obj == null)
+                        return undefined;
+                    return obj[key];
+                }, parsed);
+                return { result: JSON.stringify(result, null, indent) };
+            }
+            default:
+                throw new Error(`Unknown operation: ${operation}`);
+        }
+    },
+    renderCall(input) {
+        return `json ${input.operation}${input.path ? ` .${input.path}` : ''}`;
+    },
+    renderResult(output) {
+        return output.result.slice(0, 200);
+    },
+};

package/dist/shell.d.ts

@@ -0,0 +1,10 @@
+import type { Tool } from '@primo-ai/sdk';
+export declare const shellTool: Tool<{
+    command: string;
+    cwd?: string;
+    timeout?: number;
+}, {
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+}>;

package/dist/shell.js

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+export const shellTool = {
+    name: 'shell',
+    description: 'Execute a shell command. Returns stdout, stderr, and exit code. Supports timeout.',
+    inputSchema: z.object({
+        command: z.string().describe('Shell command to execute'),
+        cwd: z.string().optional().describe('Working directory'),
+        timeout: z
+            .number()
+            .optional()
+            .default(30_000)
+            .describe('Timeout in milliseconds (default 30s)'),
+    }),
+    requireApproval: true,
+    async execute(input) {
+        const { exec } = await import('node:child_process');
+        const { command, cwd, timeout = 30_000 } = input;
+        return new Promise((resolve) => {
+            const child = exec(command, { cwd, timeout, maxBuffer: 10 * 1024 * 1024 }, (error, stdout, stderr) => {
+                resolve({
+                    exitCode: error ? 1 : 0,
+                    stdout: stdout ?? '',
+                    stderr: stderr ?? '',
+                });
+            });
+            child.on('error', (err) => {
+                resolve({ exitCode: 1, stdout: '', stderr: err.message });
+            });
+        });
+    },
+    renderCall(input) {
+        return `$ ${input.command}`;
+    },
+    renderResult(output) {
+        const out = output.stdout.slice(0, 200);
+        return `[exit ${output.exitCode}] ${out}`;
+    },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primo-ai/tools",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -14,9 +14,10 @@
     }
   },
   "devDependencies": {
+    "@types/node": "^22.15.0",
     "typescript": "^5.7.3",
     "vitest": "^3.0.5",
-    "@primo-ai/sdk": "0.1.3"
+    "@primo-ai/sdk": "0.1.5"
   },
   "dependencies": {
     "zod": "^4.4.3"