@gizmo-ai/tools

Tool factories for Gizmo agents. Provides file system and web tools.

Install

bun add @gizmo-ai/tools

Usage

import { createRuntime } from "@gizmo-ai/runtime";
import { agentPlugin } from "@gizmo-ai/agent-plugin";
import { fsTools, webTools } from "@gizmo-ai/tools";
import { openAI } from "@gizmo-ai/model-providers";

const runtime = createRuntime({
  plugins: [
    agentPlugin({
      model: openAI(),
      tools: [
        ...fsTools({ permissions: { allowedPaths: ["/tmp/**"] } }),
        ...webTools({ search: { provider: "brave", apiKey: "..." } }),
      ],
    }),
  ],
});

File System Tools

fsTools() returns tools for file system operations:

| Tool | Description | |------|-------------| | read | Read file contents with optional line range | | write | Create or overwrite files | | edit | Make precise string replacements | | bash | Execute shell commands | | glob | Find files matching patterns | | grep | Search file contents with regex |

Configuration

fsTools({
  // Enable/disable individual tools
  tools: {
    read: true,
    write: true,
    edit: true,
    bash: false,  // Disable bash
    glob: true,
    grep: true,
  },
  // Permission restrictions
  permissions: {
    allowedPaths: ["/tmp/**", "/home/user/projects/**"],
    deniedPaths: ["/etc/**", "/home/user/.ssh/**"],
    allowedBaseCommands: ["ls", "cat", "grep"],
    shellSafetyMode: "strict_tokenized", // or "sandbox_trust" (default)
    maxFileSize: 1024 * 1024,  // 1MB
  },
})

shellSafetyMode behavior:

• sandbox_trust (default): checks base command and blocks newlines, but still allows shell metacharacters.
• strict_tokenized: rejects shell metacharacters/chaining (;, &&, ||, |, $(), redirects, etc.).

Web Tools

webTools() returns tools for web operations:

| Tool | Description | |------|-------------| | web_search | Search the web for information | | web_fetch | Fetch and parse web page content |

Configuration

webTools({
  // Enable/disable individual tools
  tools: {
    webSearch: true,
    webFetch: true,
  },
  // Search provider (required for web_search)
  search: {
    provider: "brave",  // or "tavily", "serper"
    apiKey: process.env.BRAVE_API_KEY,
  },
  // Fetch restrictions
  fetch: {
    allowedDomains: ["example.com"],
    deniedDomains: ["localhost", "127.0.0.1"],
    timeout: 10000,
    maxSize: 1024 * 1024,
  },
})

License

MIT