Built-in Tools

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

const { read, write, edit, grep, bash } = tools;

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 await wholeFoods.placeOrder({
      sku: args.sku,
      idempotencyKey: ctx.idempotencyKey,
    });
  },
});

// ✗ Bad: non-idempotent side effect without ctx
const sendEmail = defineTool({
  name: "email.send",
  schema: z.object({ to: z.string(), body: z.string() }),
  sideEffect: true,
  idempotent: false,
  async execute(args) {  // ← missing ctx parameter, Smithers warns
    await mailer.send(args);
  },
});

// ✓ Good: uses ctx.idempotencyKey to deduplicate
const sendEmail = defineTool({
  name: "email.send",
  schema: z.object({ to: z.string(), body: z.string() }),
  sideEffect: true,
  idempotent: false,
  async execute(args, ctx) {
    await mailer.send({ ...args, idempotencyKey: ctx.idempotencyKey });
  },
});

{ path: string }  // relative to rootDir or absolute

import { ToolLoopAgent as Agent } from "ai";
import { openai } from "@ai-sdk/openai";
import { read, grep } from "smthrs";

const codeAgent = new Agent({
  model: openai("gpt-5.6-sol"),
  tools: { read, grep },
});

{/* outputs comes from createSmithers() */}
<Task id="review" output={outputs.review} agent={codeAgent}>
  Read the file src/auth.ts and identify any security vulnerabilities.
</Task>

{
  path: string      // relative to rootDir or absolute
  content: string
}

import { ToolLoopAgent as Agent } from "ai";
import { openai } from "@ai-sdk/openai";
import { write, read } from "smthrs";

const writerAgent = new Agent({
  model: openai("gpt-5.6-luna"),
  tools: { write, read },
});

{
  path: string    // file to patch
  patch: string   // unified diff format
}

--- a/src/auth.ts
+++ b/src/auth.ts
@@ -10,3 +10,4 @@
   const token = jwt.sign(payload, secret);
+  logger.info("Token issued", { userId: payload.sub });
   return token;

{
  pattern: string    // regex
  path?: string      // directory or file (default: rootDir)
}

src/auth.ts:15:  if (token.expired()) {
src/auth.ts:42:  validateToken(token);
tests/auth.test.ts:8:  const token = createTestToken();

{
  cmd: string                     // executable path/name; no shell parsing
  args?: string[]                 // arguments
  opts?: { cwd?: string }        // working directory (sandboxed)
}

import { ToolLoopAgent as Agent } from "ai";
import { openai } from "@ai-sdk/openai";
import { bash } from "smthrs";

const devAgent = new Agent({
  model: openai("gpt-5.6-terra"),
  tools: { bash },
});

{/* outputs comes from createSmithers() */}
<Task id="lint" output={outputs.lint} agent={devAgent}>
  Run the linter on src/ and report any issues.
</Task>

import { ToolLoopAgent as Agent } from "ai";
import { openai } from "@ai-sdk/openai";
import { createSmithers, read, write, edit, grep, bash, Task } from "smthrs";
import { z } from "zod";

const codeAgent = new Agent({
  model: openai("gpt-5.6-luna"),
  tools: { read, write, edit, grep, bash },
  instructions: "You are a senior engineer. Use the available tools to complete tasks.",
});

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 the function in ${ctx.input.file} to improve readability.`}
    </Task>
  </Workflow>
));

import { ToolLoopAgent as Agent } from "ai";
import { openai } from "@ai-sdk/openai";
import { tools } from "smthrs";

const fullAgent = new Agent({
  model: openai("gpt-5.6-terra"),
  tools,
});

import { Effect } from "effect";
import { runWorkflow } from "smthrs";

const result = await Effect.runPromise(runWorkflow(workflow, {
  input: { file: "src/auth.ts" },
  rootDir: "/home/project",
  allowNetwork: false,
  maxOutputBytes: 500_000,
  toolTimeoutMs: 120_000,
}));