saeeol 1.2.0 → 1.2.2

package/src/tool/registry.ts

@@ -1,375 +1 @@
-import { PlanExitTool } from "./plan"
-import { Session } from "@/session/session"
-import { QuestionTool } from "./question"
-import { SuggestTool } from "../overlay/suggestion/tool" 
-import { BashTool } from "./bash"
-import { EditTool } from "./edit"
-import { GlobTool } from "./glob"
-import { GrepTool } from "./grep"
-import { ReadTool } from "./read"
-import { TaskTool } from "./task"
-import { TodoWriteTool } from "./todo"
-import { WebFetchTool } from "./webfetch"
-import { WriteTool } from "./write"
-import { InvalidTool } from "./invalid"
-import { SkillTool } from "./skill"
-import { PackageTool } from "./package"
-import * as Tool from "./tool"
-import { Config } from "@/config/config"
-import { type ToolContext as PluginToolContext, type ToolDefinition } from "@saeeol/plugin"
-import { Schema } from "effect"
-import z from "zod"
-import { ZodOverride } from "@/util/effect-zod"
-import { Plugin } from "../plugin"
-import { Provider } from "@/provider/provider"
-import { ProviderID, type ModelID } from "../provider/schema"
-import { WebSearchTool } from "./websearch"
-import { SaeeolToolRegistry } from "../overlay/tool/registry"
-import { makeRuntime } from "@/effect/run-service"
-import { Flag } from "@saeeol/core/flag/flag"
-import * as Log from "@saeeol/core/util/log"
-import { LspTool } from "./lsp"
-import * as Truncate from "./truncate"
-import { ApplyPatchTool } from "./apply_patch"
-import { Glob } from "@saeeol/core/util/glob"
-import path from "path"
-import { pathToFileURL } from "url"
-import { Effect, Layer, Context } from "effect"
-import { FetchHttpClient, HttpClient } from "effect/unstable/http"
-import { ChildProcessSpawner } from "effect/unstable/process/ChildProcessSpawner"
-import { CrossSpawnSpawner } from "@saeeol/core/cross-spawn-spawner"
-import { Ripgrep } from "../file/ripgrep"
-import { Format } from "../format"
-import { InstanceState } from "@/effect/instance-state"
-import { Question } from "../question"
-import { Todo } from "../session/todo"
-import { LSP } from "@/lsp/lsp"
-import { Instruction } from "../session/instruction"
-import { AppFileSystem } from "@saeeol/core/filesystem"
-import { Bus } from "../bus"
-import { Agent } from "../agent/agent"
-import { Skill } from "../skill"
-import { Permission } from "@/permission"
-
-const log = Log.create({ service: "tool.registry" })
-
-type TaskDef = Tool.InferDef<typeof TaskTool>
-type ReadDef = Tool.InferDef<typeof ReadTool>
-
-type State = {
-  custom: Tool.Def[]
-  builtin: Tool.Def[]
-  task: TaskDef
-  read: ReadDef
-}
-
-export interface Interface {
-  readonly ids: () => Effect.Effect<string[]>
-  readonly all: () => Effect.Effect<Tool.Def[]>
-  readonly named: () => Effect.Effect<{ task: TaskDef; read: ReadDef }>
-  readonly tools: (model: { providerID: ProviderID; modelID: ModelID; agent: Agent.Info }) => Effect.Effect<Tool.Def[]>
-}
-
-export class Service extends Context.Service<Service, Interface>()("@saeeol/ToolRegistry") {}
-
-export const layer: Layer.Layer<
-  Service,
-  never,
-  | Config.Service
-  | Plugin.Service
-  | Question.Service
-  | Todo.Service
-  | Agent.Service
-  | Skill.Service
-  | Session.Service
-  | Provider.Service
-  | LSP.Service
-  | Instruction.Service
-  | AppFileSystem.Service
-  | Bus.Service
-  | HttpClient.HttpClient
-  | ChildProcessSpawner
-  | Ripgrep.Service
-  | Format.Service
-  | Truncate.Service
-> = Layer.effect(
-  Service,
-  Effect.gen(function* () {
-    const config = yield* Config.Service
-    const plugin = yield* Plugin.Service
-    const agents = yield* Agent.Service
-    const skill = yield* Skill.Service
-    const truncate = yield* Truncate.Service
-
-    const invalid = yield* InvalidTool
-    const task = yield* TaskTool
-    const read = yield* ReadTool
-    const question = yield* QuestionTool
-    const todo = yield* TodoWriteTool
-    const lsptool = yield* LspTool
-    const plan = yield* PlanExitTool
-    const webfetch = yield* WebFetchTool
-    const websearch = yield* WebSearchTool
-    const bash = yield* BashTool
-    const globtool = yield* GlobTool
-    const writetool = yield* WriteTool
-    const edit = yield* EditTool
-    const greptool = yield* GrepTool
-    const patchtool = yield* ApplyPatchTool
-    const skilltool = yield* SkillTool
-    const packagetool = yield* PackageTool
-    const agent = yield* Agent.Service
-    const suggesttool = yield* SuggestTool
-    const saeeolToolInfos = yield* SaeeolToolRegistry.infos()
-
-    const state = yield* InstanceState.make<State>(
-      Effect.fn("ToolRegistry.state")(function* (ctx) {
-        const custom: Tool.Def[] = []
-
-        function fromPlugin(id: string, def: ToolDefinition): Tool.Def {
-          // Plugin tools define their args as a raw Zod shape. Wrap the
-          // derived Zod object in a `Schema.declare` so it slots into the
-          // Schema-typed framework, and annotate with `ZodOverride` so the
-          // walker emits the original Zod object for LLM JSON Schema.
-          const zodParams = z.object(def.args)
-          const parameters = Schema.declare<unknown>((u): u is unknown => zodParams.safeParse(u).success).annotate({
-            [ZodOverride]: zodParams,
-          })
-          return {
-            id,
-            parameters,
-            description: def.description,
-            execute: (args, toolCtx) =>
-              Effect.gen(function* () {
-                const pluginCtx: PluginToolContext = {
-                  ...toolCtx,
-                  ask: (req) => toolCtx.ask(req),
-                  directory: ctx.directory,
-                  worktree: ctx.worktree,
-                }
-                const result = yield* Effect.promise(() => def.execute(args as any, pluginCtx))
-                const output = typeof result === "string" ? result : result.output
-                const metadata = typeof result === "string" ? {} : (result.metadata ?? {})
-                const info = yield* agent.get(toolCtx.agent)
-                const out = yield* truncate.output(output, {}, info)
-                return {
-                  title: "",
-                  output: out.truncated ? out.content : output,
-                  metadata: {
-                    ...metadata,
-                    truncated: out.truncated,
-                    ...(out.truncated && { outputPath: out.outputPath }),
-                  },
-                }
-              }).pipe(
-                Effect.withSpan("Tool.execute", {
-                  attributes: {
-                    "tool.name": id,
-                    "session.id": toolCtx.sessionID,
-                    "message.id": toolCtx.messageID,
-                    ...(toolCtx.callID ? { "tool.call_id": toolCtx.callID } : {}),
-                  },
-                }),
-              ),
-          }
-        }
-
-        const dirs = yield* config.directories()
-        const matches = dirs.flatMap((dir) =>
-          Glob.scanSync("{tool,tools}/*.{js,ts}", { cwd: dir, absolute: true, dot: true, symlink: true }),
-        )
-        if (matches.length) yield* config.waitForDependencies()
-        for (const match of matches) {
-          const namespace = path.basename(match, path.extname(match))
-          // `match` is an absolute filesystem path from `Glob.scanSync(..., { absolute: true })`.
-          // Import it as `file://` so Node on Windows accepts the dynamic import.
-          const mod = yield* Effect.promise(() => import(pathToFileURL(match).href))
-          for (const [id, def] of Object.entries<ToolDefinition>(mod)) {
-            custom.push(fromPlugin(id === "default" ? namespace : `${namespace}_${id}`, def))
-          }
-        }
-
-        const plugins = yield* plugin.list()
-        for (const p of plugins) {
-          for (const [id, def] of Object.entries(p.tool ?? {})) {
-            custom.push(fromPlugin(id, def))
-          }
-        }
-
-        const cfg = yield* config.get() 
-        const questionEnabled =
-          ["app", "cli", "desktop", "vscode"].includes(Flag.SAEEOL_CLIENT) || Flag.SAEEOL_ENABLE_QUESTION_TOOL 
-
-        const tool = yield* Effect.all({
-          invalid: Tool.init(invalid),
-          bash: Tool.init(bash),
-          read: Tool.init(read),
-          glob: Tool.init(globtool),
-          grep: Tool.init(greptool),
-          edit: Tool.init(edit),
-          write: Tool.init(writetool),
-          task: Tool.init(task),
-          fetch: Tool.init(webfetch),
-          todo: Tool.init(todo),
-          search: Tool.init(websearch),
-          skill: Tool.init(skilltool),
-          package: Tool.init(packagetool),
-          patch: Tool.init(patchtool),
-          question: Tool.init(question),
-          lsp: Tool.init(lsptool),
-          plan: Tool.init(plan),
-          suggest: Tool.init(suggesttool), 
-        })
-
-        const saeeol = yield* SaeeolToolRegistry.build(saeeolToolInfos, { agent: agents, truncate }) 
-
-        return {
-          custom,
-          builtin: SaeeolToolRegistry.describe(
-            [
-              tool.invalid,
-              ...(questionEnabled ? [tool.question] : []),
-              tool.bash,
-              tool.read,
-              tool.glob,
-              tool.grep,
-              tool.edit,
-              tool.write,
-              tool.task,
-              tool.fetch,
-              tool.todo,
-              tool.search,
-              tool.skill,
-              tool.package,
-              tool.patch,
-              tool.plan,
-              ...(["cli", "vscode"].includes(Flag.SAEEOL_CLIENT) ? [tool.suggest] : []),
-              ...SaeeolToolRegistry.extra(saeeol, cfg),
-              ...(Flag.SAEEOL_EXPERIMENTAL_LSP_TOOL ? [tool.lsp] : []),
-            ],
-            saeeol,
-          ), 
-          task: tool.task,
-          read: tool.read,
-        }
-      }),
-    )
-
-    const all: Interface["all"] = Effect.fn("ToolRegistry.all")(function* () {
-      const s = yield* InstanceState.get(state)
-      return [...s.builtin, ...s.custom] as Tool.Def[]
-    })
-
-    const ids: Interface["ids"] = Effect.fn("ToolRegistry.ids")(function* () {
-      return (yield* all()).map((tool) => tool.id)
-    })
-
-    const describeSkill = Effect.fn("ToolRegistry.describeSkill")(function* (agent: Agent.Info) {
-      const list = yield* skill.available(agent)
-      if (list.length === 0) return "No skills are currently available."
-      return [
-        "Load a specialized skill that provides domain-specific instructions and workflows.",
-        "",
-        "When you recognize that a task matches one of the available skills listed below, use this tool to load the full skill instructions.",
-        "",
-        "The skill will inject detailed instructions, workflows, and access to bundled resources (scripts, references, templates) into the conversation context.",
-        "",
-        'Tool output includes a `<skill_content name="...">` block with the loaded content.',
-        "",
-        "The following skills provide specialized sets of instructions for particular tasks",
-        "Invoke this tool to load a skill when a task matches one of the available skills listed below:",
-        "",
-        Skill.fmt(list, { verbose: false }),
-      ].join("\n")
-    })
-
-    const describeTask = Effect.fn("ToolRegistry.describeTask")(function* (agent: Agent.Info) {
-      const items = (yield* agents.list()).filter((item) => item.mode !== "primary")
-      const filtered = items.filter(
-        (item) => Permission.evaluate("task", item.name, agent.permission).action !== "deny",
-      )
-      const list = filtered.toSorted((a, b) => a.name.localeCompare(b.name))
-      const description = list
-        .map(
-          (item) =>
-            `- ${item.name}: ${item.description ?? "This subagent should only be called manually by the user."}`,
-        )
-        .join("\n")
-      return ["Available agent types and the tools they have access to:", description].join("\n")
-    })
-
-    const tools: Interface["tools"] = Effect.fn("ToolRegistry.tools")(function* (input) {
-      const filtered = (yield* all()).filter((tool) => {
-        if (tool.id === WebSearchTool.id) {
-          return input.providerID === ProviderID.saeeol || Flag.SAEEOL_ENABLE_EXA 
-        }
-
-        const usePatch =
-          !!process.env["SAEEOL_E2E_LLM_URL"] ||
-          (input.modelID.includes("gpt-") && !input.modelID.includes("oss") && !input.modelID.includes("gpt-4"))
-        if (tool.id === ApplyPatchTool.id) return usePatch
-        if (tool.id === EditTool.id) return !usePatch 
-
-        return true
-      })
-
-      return yield* Effect.forEach(
-        filtered,
-        Effect.fnUntraced(function* (tool: Tool.Def) {
-          using _ = log.time(tool.id)
-          const output = {
-            description: tool.description,
-            parameters: tool.parameters,
-          }
-          yield* plugin.trigger("tool.definition", { toolID: tool.id }, output)
-          return {
-            id: tool.id,
-            description: [
-              output.description,
-              tool.id === TaskTool.id ? yield* describeTask(input.agent) : undefined,
-              tool.id === SkillTool.id ? yield* describeSkill(input.agent) : undefined,
-            ]
-              .filter(Boolean)
-              .join("\n"),
-            parameters: output.parameters,
-            execute: tool.execute,
-            formatValidationError: tool.formatValidationError,
-          }
-        }),
-        { concurrency: "unbounded" },
-      )
-    })
-
-    const named: Interface["named"] = Effect.fn("ToolRegistry.named")(function* () {
-      const s = yield* InstanceState.get(state)
-      return { task: s.task, read: s.read }
-    })
-
-    return Service.of({ ids, all, named, tools })
-  }),
-)
-
-export const defaultLayer = Layer.suspend(() =>
-  layer.pipe(
-    Layer.provide(Config.defaultLayer),
-    Layer.provide(Plugin.defaultLayer),
-    Layer.provide(Question.defaultLayer),
-    Layer.provide(Todo.defaultLayer),
-    Layer.provide(Skill.defaultLayer),
-    Layer.provide(Agent.defaultLayer),
-    Layer.provide(Session.defaultLayer),
-    Layer.provide(Provider.defaultLayer),
-    Layer.provide(LSP.defaultLayer),
-    Layer.provide(Instruction.defaultLayer),
-    Layer.provide(AppFileSystem.defaultLayer),
-    Layer.provide(Bus.layer),
-    Layer.provide(FetchHttpClient.layer),
-    Layer.provide(Format.defaultLayer),
-    Layer.provide(CrossSpawnSpawner.defaultLayer),
-    Layer.provide(Ripgrep.defaultLayer),
-    Layer.provide(Truncate.defaultLayer),
-  ),
-)
-const { runPromise } = makeRuntime(Service, defaultLayer)
-export const ids = () => runPromise((svc) => svc.ids())
-export * as ToolRegistry from "./registry"
+export * from "./integration/registry"

package/src/tool/schema.ts

@@ -1,16 +1 @@
-import { Schema } from "effect"
-
-import { Identifier } from "@/id/id"
-import { zod, ZodOverride } from "@/util/effect-zod"
-import { withStatics } from "@/util/schema"
-
-const toolIdSchema = Schema.String.annotate({ [ZodOverride]: Identifier.schema("tool") }).pipe(Schema.brand("ToolID"))
-
-export type ToolID = typeof toolIdSchema.Type
-
-export const ToolID = toolIdSchema.pipe(
-  withStatics((schema: typeof toolIdSchema) => ({
-    ascending: (id?: string) => schema.make(Identifier.ascending("tool", id)),
-    zod: zod(schema),
-  })),
-)
+export * from "./core/schema"

package/src/tool/search/glob.ts

@@ -0,0 +1,115 @@
+import path from "path"
+import { Effect, Option, Schema } from "effect"
+import * as Stream from "effect/Stream"
+import { InstanceState } from "@/effect/instance-state"
+import { AppFileSystem } from "@saeeol/core/filesystem"
+import { Ripgrep } from "../../file/ripgrep"
+import { assertExternalDirectoryEffect } from "../core/external-directory"
+import DESCRIPTION from "./glob.txt"
+import * as Tool from "../core/tool"
+function normalize(p: string) {
+  return p.replaceAll("\\", "/")
+}
+
+function split(pattern: string) {
+  const normalized = normalize(pattern)
+  if (!path.isAbsolute(normalized)) return
+  const index = normalized.search(/[*?{[]/)
+  if (index === -1) return { dir: normalized, pattern: "*" }
+  const slice = normalized.slice(0, index)
+  const cut = slice.lastIndexOf("/")
+  const dir = cut > 0 ? slice.slice(0, cut) : "/"
+  const next = normalized.slice(cut + 1)
+  return { dir, pattern: next || "*" }
+}
+
+export const Parameters = Schema.Struct({
+  pattern: Schema.String.annotate({ description: "The glob pattern to match files against" }),
+  path: Schema.optional(Schema.String).annotate({
+    description: `The directory to search in. If not specified, the current working directory will be used. IMPORTANT: Omit this field to use the default directory. DO NOT enter "undefined" or "null" - simply omit it for the default behavior. Must be a valid directory path if provided.`,
+  }),
+})
+
+export const GlobTool = Tool.define(
+  "glob",
+  Effect.gen(function* () {
+    const rg = yield* Ripgrep.Service
+    const fs = yield* AppFileSystem.Service
+
+    return {
+      description: DESCRIPTION,
+      parameters: Parameters,
+      execute: (params: { pattern: string; path?: string }, ctx: Tool.Context) =>
+        Effect.gen(function* () {
+          const ins = yield* InstanceState.context
+          const absolute = split(params.pattern) 
+          yield* ctx.ask({
+            permission: "glob",
+            patterns: [params.pattern],
+            always: ["*"],
+            metadata: {
+              pattern: params.pattern,
+              path: params.path,
+            },
+          })
+
+          const base = absolute?.dir ?? params.path ?? ins.directory 
+          const search = path.isAbsolute(base) ? base : path.resolve(ins.directory, base)
+          const info = yield* fs.stat(search).pipe(Effect.catch(() => Effect.succeed(undefined)))
+          if (info?.type === "File") {
+            throw new Error(`glob path must be a directory: ${search}`)
+          }
+          yield* assertExternalDirectoryEffect(ctx, search, { kind: "directory" })
+
+          const limit = 100
+          let truncated = false
+          const files = yield* rg
+            .files({ cwd: search, glob: [absolute?.pattern ?? params.pattern], signal: ctx.abort }) 
+            .pipe(
+              Stream.mapEffect((file) =>
+                Effect.gen(function* () {
+                  const full = path.resolve(search, file)
+                  const info = yield* fs.stat(full).pipe(Effect.catch(() => Effect.succeed(undefined)))
+                  const mtime =
+                    info?.mtime.pipe(
+                      Option.map((date) => date.getTime()),
+                      Option.getOrElse(() => 0),
+                    ) ?? 0
+                  return { path: full, mtime }
+                }),
+              ),
+              Stream.take(limit + 1),
+              Stream.runCollect,
+              Effect.map((chunk) => [...chunk]),
+            )
+
+          if (files.length > limit) {
+            truncated = true
+            files.length = limit
+          }
+          files.sort((a, b) => b.mtime - a.mtime)
+
+          const output = []
+          if (files.length === 0) output.push("No files found")
+          if (files.length > 0) {
+            output.push(...files.map((file) => file.path))
+            if (truncated) {
+              output.push("")
+              output.push(
+                `(Results are truncated: showing first ${limit} results. Consider using a more specific path or pattern.)`,
+              )
+            }
+          }
+
+          return {
+            title: path.relative(ins.worktree, search),
+            metadata: {
+              count: files.length,
+              truncated,
+            },
+            output: output.join("\n"),
+          }
+        }).pipe(Effect.orDie),
+    }
+  }),
+)

package/src/tool/search/glob.txt

@@ -0,0 +1,6 @@
+- Fast file pattern matching tool that works with any codebase size
+- Supports glob patterns like "**/*.js" or "src/**/*.ts"
+- Returns matching file paths sorted by modification time
+- Use this tool when you need to find files by name patterns
+- When you are doing an open-ended search that may require multiple rounds of globbing and grepping, use the Task tool instead
+- You have the capability to call multiple tools in a single response. It is always better to speculatively perform multiple searches as a batch that are potentially useful.

package/src/tool/search/grep.ts

@@ -0,0 +1,151 @@
+import path from "path"
+import { Schema } from "effect"
+import { Effect, Option } from "effect"
+import { InstanceState } from "@/effect/instance-state"
+import { AppFileSystem } from "@saeeol/core/filesystem"
+import { Ripgrep } from "../../file/ripgrep"
+import { assertExternalDirectoryEffect } from "../core/external-directory"
+import DESCRIPTION from "./grep.txt"
+import * as Tool from "../core/tool"
+
+const MAX_LINE_LENGTH = 2000
+
+export const Parameters = Schema.Struct({
+  pattern: Schema.String.annotate({ description: "The regex pattern to search for in file contents" }),
+  path: Schema.optional(Schema.String).annotate({
+    description: "The directory to search in. Defaults to the current working directory.",
+  }),
+  include: Schema.optional(Schema.String).annotate({
+    description: 'File pattern to include in the search (e.g. "*.js", "*.{ts,tsx}")',
+  }),
+})
+
+export const GrepTool = Tool.define(
+  "grep",
+  Effect.gen(function* () {
+    const fs = yield* AppFileSystem.Service
+    const rg = yield* Ripgrep.Service
+
+    return {
+      description: DESCRIPTION,
+      parameters: Parameters,
+      execute: (params: { pattern: string; path?: string; include?: string }, ctx: Tool.Context) =>
+        Effect.gen(function* () {
+          const empty = {
+            title: params.pattern,
+            metadata: { matches: 0, truncated: false },
+            output: "No files found",
+          }
+          if (!params.pattern) {
+            throw new Error("pattern is required")
+          }
+
+          yield* ctx.ask({
+            permission: "grep",
+            patterns: [params.pattern],
+            always: ["*"],
+            metadata: {
+              pattern: params.pattern,
+              path: params.path,
+              include: params.include,
+            },
+          })
+
+          const ins = yield* InstanceState.context
+          const search = AppFileSystem.resolve(
+            path.isAbsolute(params.path ?? ins.directory)
+              ? (params.path ?? ins.directory)
+              : path.join(ins.directory, params.path ?? "."),
+          )
+          const info = yield* fs.stat(search).pipe(Effect.catch(() => Effect.succeed(undefined)))
+          const cwd = info?.type === "Directory" ? search : path.dirname(search)
+          const file = info?.type === "Directory" ? undefined : [path.relative(cwd, search)]
+          yield* assertExternalDirectoryEffect(ctx, search, {
+            kind: info?.type === "Directory" ? "directory" : "file",
+          })
+
+          const result = yield* rg.search({
+            cwd,
+            pattern: params.pattern,
+            glob: params.include ? [params.include] : undefined,
+            file,
+            signal: ctx.abort,
+          })
+          if (result.items.length === 0) return empty
+
+          const rows = result.items.map((item) => ({
+            path: AppFileSystem.resolve(
+              path.isAbsolute(item.path.text) ? item.path.text : path.join(cwd, item.path.text),
+            ),
+            line: item.line_number,
+            text: item.lines.text,
+          }))
+          const times = new Map(
+            (yield* Effect.forEach(
+              [...new Set(rows.map((row) => row.path))],
+              Effect.fnUntraced(function* (file) {
+                const info = yield* fs.stat(file).pipe(Effect.catch(() => Effect.succeed(undefined)))
+                if (!info || info.type === "Directory") return undefined
+                return [
+                  file,
+                  info.mtime.pipe(
+                    Option.map((time) => time.getTime()),
+                    Option.getOrElse(() => 0),
+                  ) ?? 0,
+                ] as const
+              }),
+              { concurrency: 16 },
+            )).filter((entry): entry is readonly [string, number] => Boolean(entry)),
+          )
+          const matches = rows.flatMap((row) => {
+            const mtime = times.get(row.path)
+            if (mtime === undefined) return []
+            return [{ ...row, mtime }]
+          })
+
+          matches.sort((a, b) => b.mtime - a.mtime)
+
+          const limit = 100
+          const truncated = matches.length > limit
+          const final = truncated ? matches.slice(0, limit) : matches
+          if (final.length === 0) return empty
+
+          const total = matches.length
+          const output = [`Found ${total} matches${truncated ? ` (showing first ${limit})` : ""}`]
+
+          let current = ""
+          for (const match of final) {
+            if (current !== match.path) {
+              if (current !== "") output.push("")
+              current = match.path
+              output.push(`${match.path}:`)
+            }
+            const text =
+              match.text.length > MAX_LINE_LENGTH ? match.text.substring(0, MAX_LINE_LENGTH) + "..." : match.text
+            output.push(`  Line ${match.line}: ${text}`)
+          }
+
+          if (truncated) {
+            output.push("")
+            output.push(
+              `(Results truncated: showing ${limit} of ${total} matches (${total - limit} hidden). Consider using a more specific path or pattern.)`,
+            )
+          }
+
+          if (result.partial) {
+            output.push("")
+            output.push("(Some paths were inaccessible and skipped)")
+          }
+
+          return {
+            title: params.pattern,
+            metadata: {
+              matches: total,
+              truncated,
+            },
+            output: output.join("\n"),
+          }
+        }).pipe(Effect.orDie),
+    }
+  }),
+)

package/src/tool/search/grep.txt

@@ -0,0 +1,8 @@
+- Fast content search tool that works with any codebase size
+- Searches file contents using regular expressions
+- Supports full regex syntax (eg. "log.*Error", "function\s+\w+", etc.)
+- Filter files by pattern with the include parameter (eg. "*.js", "*.{ts,tsx}")
+- Returns file paths and line numbers with at least one match sorted by modification time
+- Use this tool when you need to find files containing specific patterns
+- If you need to identify/count the number of matches within files, use the Bash tool with `rg` (ripgrep) directly. Do NOT use `grep`.
+- When you are doing a deep search that may require multiple tool invocations, use the Task tool instead