Tools API

A tool is an AI SDK tool an agent may call. defineTool wraps one with Smithers runtime context: a deterministic idempotency key, side-effect metadata, and the side-effect snapshot hook. The five built-in tools (read, write, edit, grep, bash) are themselves defineTool results, run inside the task’s sandbox.

import {
  defineTool,
  getDefinedToolMetadata,
  bash,
  read,
  write,
  edit,
  grep,
  tools,
} from "smthrs";

defineTool

Wrap a Zod-validated execute function into a durable AI SDK tool, passed to an agent’s tools or a <Task>’s tools prop.

function defineTool<S extends ZodType>(options: DefineToolOptions<S>): Tool;

string

required

Tool name surfaced to the agent and stamped onto ctx.toolName. Also the default description.

string

Human-readable description the agent sees. Defaults to name.

ZodType

required

Zod schema for the tool’s input, validated by the AI SDK before execute runs with the parsed args.

boolean

default:"false"

Marks the tool as mutating external state: opts it into Smithers side-effect tracking and runs the durability snapshot hook after execute.

boolean

default:"!sideEffect"

Whether re-running with the same input is safe; defaults to true when sideEffect is false. With sideEffect: true, idempotent: false, retries inject a warning that the tool was already called, so the agent can verify external state first.

(args, ctx) => Promise<unknown>

required

Runs the tool: args is the parsed input, ctx is the tool context. If sideEffect: true, idempotent: false and execute omits ctx, Smithers logs a startup warning, since ctx.idempotencyKey is needed to handle retries safely.

Show ctx: ToolContext

string

Deterministic per task + iteration, stable across retries and resumes. Pass it to idempotency-aware external APIs (Stripe, AWS) to deduplicate.

string

The tool’s name.

boolean

Resolved sideEffect flag.

boolean

Resolved idempotent flag.

string

Current run id (RUN_ID).

string

Task node that invoked the tool (NODE_ID).

number

Loop iteration index.

number

Retry attempt number.

number

Task-local tool-call sequence counter.

string

default:"process.cwd()"

Sandbox root; paths resolve against it, escapes rejected.

boolean

default:"false"

Whether network commands are permitted (used by bash).

number

default:"200000"

Output size limit (200KB).

number

default:"60000"

Process timeout for bash and grep (60s).

(name, toolUseId) => Promise<unknown>

Side-effect snapshot hook. No-op unless the engine supplies a real handle; snapshot failures never fail the tool.

object

An AI SDK tool with attached Smithers metadata. Read the metadata with getDefinedToolMetadata.

import { defineTool } from "smthrs";
import { z } from "zod";

const placeOrder = defineTool({
  name: "wholefoods.place_order",
  description: "Place a grocery order",
  schema: z.object({ sku: z.string() }),
  sideEffect: true,
  idempotent: false,
  async execute(args, ctx) {
    return wholeFoods.placeOrder({
      sku: args.sku,
      idempotencyKey: ctx.idempotencyKey,
    });
  },
});

The sideEffect / idempotent pair drives retry behavior:

`sideEffect`	`idempotent`	Behavior
`false`	`true`	Pure read. Replayed freely. No warnings.
`true`	`true`	Mutates, but replay-safe (upsert, PUT). No warnings.
`true`	`false`	Mutates, not replay-safe (send email, charge payment). Retry warns the agent with a stable `ctx.idempotencyKey`.

The rule: if you cannot undo it with git reset, mark it sideEffect: true. Source defineTool.js · context.js · Tests tools-unit.test.js, define-tool-durability.test.js · See also Built-in Tools, SDK agents

getDefinedToolMetadata

Read the Smithers metadata attached by defineTool. Returns null for plain AI SDK tools or non-objects.

function getDefinedToolMetadata(value: unknown):
  | { name: string; sideEffect: boolean; idempotent: boolean }
  | null;

unknown

required

A tool (or any value). Inspected for the Symbol.for("smithers.tool.metadata") property.

object | null

Show metadata

string

The tool’s name.

boolean

Resolved side-effect flag.

boolean

Resolved idempotency flag.

import { getDefinedToolMetadata, write } from "smthrs";

getDefinedToolMetadata(write);
// { name: "write", sideEffect: true, idempotent: false }

Source defineTool.js · Tests tools-unit.test.js · See also defineTool

Built-in tools

Five defineTool results, all sandboxed to ctx.rootDir (the workflow directory by default): paths resolve against the root, symlink escapes are rejected, and output truncates to ctx.maxOutputBytes (200KB). Import them individually or as the tools bundle:

import { tools } from "smthrs";
// tools === { read, write, edit, bash, grep }
const { read, write, edit, bash, grep } = tools;

Tool	`sideEffect`	`idempotent`
`read`	`false`	`true`
`grep`	`false`	`true`
`write`	`true`	`false`
`edit`	`true`	`false`
`bash`	`true`	`false`

read

Read a UTF-8 file from the sandbox.

string

required

File path, relative to rootDir or absolute within it.

Returns the file contents, throwing if it exceeds maxOutputBytes.

write

Write content to a file, creating parent directories as needed.

string

required

Destination path, relative to rootDir or absolute within it.

string

required

File contents.

Returns "ok". Throws TOOL_CONTENT_TOO_LARGE if content exceeds maxOutputBytes; only the content’s byte size and SHA-256 hash are logged, never the content itself.

edit

Apply a unified-diff patch to an existing file.

string

required

File to patch. Must already exist.

string

required

A unified diff. Applied against the current contents.

Returns "ok". Throws TOOL_PATCH_TOO_LARGE (patch over maxOutputBytes) or TOOL_PATCH_FAILED (the patch context does not match the file).

grep

Search for a pattern with ripgrep (rg -n). Requires rg on PATH.

string

required

Regex to search for.

string

default:"."

Directory or file to search, relative to rootDir.

Returns matching lines as file:line:text. No matches returns an empty string; an rg error (exit code 2) throws TOOL_GREP_FAILED.

bash

Run an executable with arguments. There is no shell parsing: pass arguments via args, and for pipes or redirects invoke a shell explicitly, e.g. { cmd: "sh", args: ["-lc", "..."] }.

string

required

Executable name or path. Up to 8,192 characters.

string[]

Arguments. Up to 128 entries, each up to 8,192 characters.

{ cwd?: string }

cwd sets the working directory (sandboxed under rootDir). Defaults to rootDir.

Returns combined stdout and stderr, truncated to maxOutputBytes. A non-zero exit code throws TOOL_COMMAND_FAILED; the process is killed with SIGKILL after ctx.timeoutMs (default 60s, hard cap one hour).

Network is blocked unless allowNetwork is enabled (RunOptions, --allow-network, or server config): Smithers then rejects commands whose executable basename is curl, wget, npm, bun, or pip, any argument that is itself a http:// or https:// URL (whole argument or --flag=<url> value), and git whose subcommand is push, pull, fetch, clone, or remote (throwing TOOL_NETWORK_DISABLED or TOOL_GIT_REMOTE_DISABLED). Only the invoked executable and real URL arguments are matched, so local commands such as git status or git commit -m "fetch upstream changes" are allowed. A shell -c payload (sh -c "curl https://x") is matched in command position, so it is blocked too.

This denylist is not isolation on Linux. True OS-level network isolation exists only on macOS, where a blocked bash runs under sandbox-exec with a network-deny profile (if available). Elsewhere, including Smithers’ CI, cloud, and production environments, allowNetwork:false cannot enforce a kernel sandbox and falls back to the denylist above: best-effort defense-in-depth, not a security boundary, trivially bypassed by a shell, an interpreter (python -c assembling a URL from parts, bash /dev/tcp), or a renamed binary. When isolation is unenforced, Smithers logs a TOOL_NETWORK_ISOLATION_UNENFORCED observability warning. Do not rely on allowNetwork:false to sandbox untrusted code; run it under a real <Sandbox> provider with egress controls instead.

import { ToolLoopAgent as Agent } from "ai";
import { openai } from "@ai-sdk/openai";
import { createSmithers, tools, Task } from "smthrs";
import { z } from "zod";

const codeAgent = new Agent({
  model: openai("gpt-5.6-luna"),
  tools, // { read, write, edit, bash, grep }
});

const { Workflow, smithers, outputs } = createSmithers({
  result: z.object({ summary: z.string() }),
});

export default smithers((ctx) => (
  <Workflow name="refactor">
    <Task id="refactor" output={outputs.result} agent={codeAgent}>
      {`Refactor ${ctx.input.file} for readability and run the tests.`}
    </Task>
  </Workflow>
));

Source tools/index.js · bash.js, read.js, write.js, edit.js, grep.js · Tests tools-unit.test.js · See also Built-in Tools, Common External Tools, SDK agents

Overview

Core API

Runtime

Types & errors

Gateway RPC

defineTool

getDefinedToolMetadata

Built-in tools

read

write

edit

grep

bash

​defineTool

​getDefinedToolMetadata

​Built-in tools

​read

​write

​edit

​grep

​bash

defineTool

getDefinedToolMetadata

Built-in tools

read

write

edit

grep

bash