@alumbwe/anvil 1.0.20 → 1.0.21

package/vendor/@anvil/common/src/tools/params/tool/list-directory.ts

@@ -0,0 +1,58 @@
+import z from 'zod/v4'
+
+import { $getNativeToolCallExampleString, jsonToolResultSchema } from '../utils'
+
+import type { $ToolParams } from '../../constants'
+
+const toolName = 'list_directory'
+const endsAgentStep = true
+const inputSchema = z
+  .object({
+    path: z
+      .string()
+      .describe('Directory path to list, relative to the project root.'),
+  })
+  .describe(
+    'List files and directories in the specified path. Returns separate arrays of file names and directory names.',
+  )
+const description = `
+Lists all files and directories in the specified path. Useful for exploring directory structure and finding files.
+
+Example:
+${$getNativeToolCallExampleString({
+  toolName,
+  inputSchema,
+  input: {
+    path: 'src/components',
+  },
+  endsAgentStep,
+})}
+
+${$getNativeToolCallExampleString({
+  toolName,
+  inputSchema,
+  input: {
+    path: '.',
+  },
+  endsAgentStep,
+})}
+    `.trim()
+
+export const listDirectoryParams = {
+  toolName,
+  endsAgentStep,
+  description,
+  inputSchema,
+  outputSchema: jsonToolResultSchema(
+    z.union([
+      z.object({
+        files: z.array(z.string()).describe('Array of file names'),
+        directories: z.array(z.string()).describe('Array of directory names'),
+        path: z.string().describe('The directory path that was listed'),
+      }),
+      z.object({
+        errorMessage: z.string(),
+      }),
+    ]),
+  ),
+} satisfies $ToolParams

package/vendor/@anvil/common/src/tools/params/tool/lookup-agent-info.ts

@@ -0,0 +1,37 @@
+import z from 'zod/v4'
+
+import { jsonValueSchema } from '../../../types/json'
+import { $getNativeToolCallExampleString, jsonToolResultSchema } from '../utils'
+
+import type { $ToolParams } from '../../constants'
+
+const toolName = 'lookup_agent_info'
+const endsAgentStep = false
+const inputSchema = z
+  .object({
+    agentId: z
+      .string()
+      .describe('Agent ID (short local or full published format)'),
+  })
+  .describe('Retrieve information about an agent by ID')
+const description = `
+Retrieve information about an agent by ID for proper spawning. Use this when you see a request with a full agent ID like "@publisher/agent-id@version" to validate the agent exists and get its metadata. Only agents that are published under a publisher and version are supported for this tool. 
+
+Example:
+${$getNativeToolCallExampleString({
+  toolName,
+  inputSchema,
+  input: {
+    agentId: 'anvil/researcher@0.0.1',
+  },
+  endsAgentStep,
+})}
+`.trim()
+
+export const lookupAgentInfoParams = {
+  toolName,
+  endsAgentStep,
+  description,
+  inputSchema,
+  outputSchema: jsonToolResultSchema(jsonValueSchema),
+} satisfies $ToolParams

package/vendor/@anvil/common/src/tools/params/tool/propose-str-replace.ts

@@ -0,0 +1,103 @@
+import z from 'zod/v4'
+
+import {
+  $getNativeToolCallExampleString,
+  coerceToArray,
+  jsonToolResultSchema,
+  normalizeReplacementAliases,
+} from '../utils'
+
+import type { $ToolParams } from '../../constants'
+
+export const proposeUpdateFileResultSchema = z.union([
+  z.object({
+    file: z.string(),
+    message: z.string(),
+    unifiedDiff: z.string(),
+  }),
+  z.object({
+    file: z.string(),
+    errorMessage: z.string(),
+  }),
+])
+
+const toolName = 'propose_str_replace'
+const endsAgentStep = false
+const inputSchema = z
+  .object({
+    path: z
+      .string()
+      .min(1, 'Path cannot be empty')
+      .describe(`The path to the file to edit.`),
+    replacements: z
+      .preprocess(
+        coerceToArray,
+        z
+          .array(
+            z
+              .preprocess(
+                normalizeReplacementAliases,
+                z.object({
+                  oldString: z
+                    .string()
+                    .min(1, 'oldString cannot be empty')
+                    .describe(
+                      `The string to replace. This must be an *exact match* of the string you want to replace, including whitespace and punctuation.`,
+                    ),
+                  newString: z
+                    .string()
+                    .describe(
+                      `The string to replace the corresponding oldString with. Can be empty to delete.`,
+                    ),
+                  allowMultiple: z
+                    .boolean()
+                    .optional()
+                    .default(false)
+                    .describe(
+                      'Whether to allow multiple replacements of oldString.',
+                    ),
+                }),
+              )
+              .describe('Pair of oldString and newString values.'),
+          )
+          .min(1, 'Replacements cannot be empty'),
+      )
+      .describe('Array of replacements to make.'),
+  })
+  .describe(
+    `Propose string replacements in a file without actually applying them.`,
+  )
+const description = `
+Propose edits to a file without actually applying them. Use this tool when you want to draft changes that will be reviewed before being applied.
+
+This tool works identically to str_replace but the changes are not written to disk. Instead, it returns the unified diff of what would change. Multiple propose calls on the same file will stack correctly.
+
+Example:
+${$getNativeToolCallExampleString({
+  toolName,
+  inputSchema,
+  input: {
+    path: 'path/to/file',
+    replacements: [
+      {
+        oldString: 'This is the old string',
+        newString: 'This is the new string',
+      },
+      {
+        oldString: '\nfoo:',
+        newString: '\nbar:',
+        allowMultiple: true,
+      },
+    ],
+  },
+  endsAgentStep,
+})}
+    `.trim()
+
+export const proposeStrReplaceParams = {
+  toolName,
+  endsAgentStep,
+  description,
+  inputSchema,
+  outputSchema: jsonToolResultSchema(proposeUpdateFileResultSchema),
+} satisfies $ToolParams

package/vendor/@anvil/common/src/tools/params/tool/propose-write-file.ts

@@ -0,0 +1,71 @@
+import z from 'zod/v4'
+
+import { proposeUpdateFileResultSchema } from './propose-str-replace'
+import { $getNativeToolCallExampleString, jsonToolResultSchema } from '../utils'
+
+import type { $ToolParams } from '../../constants'
+
+const toolName = 'propose_write_file'
+const endsAgentStep = false
+const inputSchema = z
+  .object({
+    path: z
+      .string()
+      .min(1, 'Path cannot be empty')
+      .describe(`Path to the file relative to the **project root**`),
+    instructions: z
+      .string()
+      .describe('What the change is intended to do in only one sentence.'),
+    content: z.string().describe(`Complete file content to write to the file.`),
+  })
+  .describe(
+    `Propose creating or editing a file without actually applying the changes.`,
+  )
+const description = `
+Propose creating or editing a file without actually applying the changes.
+
+This tool works identically to write_file but the changes are not written to disk. Instead, it returns the unified diff of what would change. Each call overwrites the previous call.
+
+Format the \`content\` parameter with the entire content of the file.
+
+This tool is to be used in subagents.
+
+Example - Simple file creation:
+${$getNativeToolCallExampleString({
+  toolName,
+  inputSchema,
+  input: {
+    path: 'new-file.ts',
+    instructions: 'Prints Hello, world',
+    content: 'console.log("Hello, world!");',
+  },
+  endsAgentStep,
+})}
+
+Example - Overwriting a file:
+${$getNativeToolCallExampleString({
+  toolName,
+  inputSchema,
+  input: {
+    path: 'foo.ts',
+    instructions: 'Update foo function',
+    content: `function foo() {
+  doSomethingNew();
+}
+  
+function bar() {
+  doSomethingOld();
+}
+`,
+  },
+  endsAgentStep,
+})}
+`.trim()
+
+export const proposeWriteFileParams = {
+  toolName,
+  endsAgentStep,
+  description,
+  inputSchema,
+  outputSchema: jsonToolResultSchema(proposeUpdateFileResultSchema),
+} satisfies $ToolParams

package/vendor/@anvil/common/src/tools/params/tool/read-docs.ts

@@ -0,0 +1,90 @@
+import z from 'zod/v4'
+
+import { $getNativeToolCallExampleString, jsonToolResultSchema } from '../utils'
+
+import type { $ToolParams } from '../../constants'
+
+const toolName = 'read_docs'
+const endsAgentStep = true
+const inputSchema = z
+  .object({
+    libraryTitle: z
+      .string()
+      .trim()
+      .min(1, 'Library title cannot be empty')
+      .describe(
+        `The library or framework name (e.g., "Next.js", "MongoDB", "React"). Use the official name as it appears in documentation if possible. Only public libraries available in Context7's database are supported, so small or private libraries may not be available.`,
+      ),
+    topic: z
+      .string()
+      .trim()
+      .min(1, 'Topic cannot be empty')
+      .describe(
+        `Specific topic to focus on (e.g., "routing", "hooks", "authentication")`,
+      ),
+    max_tokens: z
+      .number()
+      .int()
+      .positive()
+      .default(10_000)
+      .optional()
+      .describe(
+        `Optional maximum number of tokens to return. Defaults to 10000.`,
+      ),
+  })
+  .describe(
+    `Fetch up-to-date documentation for libraries and frameworks using Context7 API.`,
+  )
+const description = `
+Purpose: Get current, accurate documentation for popular libraries, frameworks, and technologies. This tool searches Context7's database of up-to-date documentation and returns relevant content.
+
+**IMPORTANT**: The \`libraryTitle\` parameter should be the exact, official name of the library or framework, not a search query. Think of it as looking up a specific book title in a library catalog.
+
+Correct examples:
+- "Next.js" (not "nextjs tutorial" or "how to use nextjs")
+- "React" (not "react hooks guide")
+- "MongoDB" (not "mongodb database setup")
+- "Express.js" (not "express server")
+
+Use cases:
+- Getting current API documentation for a library
+- Finding usage examples and best practices
+- Understanding how to implement specific features
+- Checking the latest syntax and methods
+
+The tool will search for the library and return the most relevant documentation content. If a topic is specified, it will focus the results on that specific area.
+
+Example:
+${$getNativeToolCallExampleString({
+  toolName,
+  inputSchema,
+  input: {
+    libraryTitle: 'Next.js',
+    topic: 'app router',
+    max_tokens: 15000,
+  },
+  endsAgentStep,
+})}
+
+${$getNativeToolCallExampleString({
+  toolName,
+  inputSchema,
+  input: {
+    libraryTitle: 'MongoDB',
+    topic: 'database setup',
+  },
+  endsAgentStep,
+})}
+`.trim()
+
+export const readDocsParams = {
+  toolName,
+  endsAgentStep,
+  description,
+  inputSchema,
+  outputSchema: jsonToolResultSchema(
+    z.object({
+      documentation: z.string(),
+    }),
+  ),
+} satisfies $ToolParams

package/vendor/@anvil/common/src/tools/params/tool/read-files.ts

@@ -0,0 +1,109 @@
+import z from 'zod/v4'
+
+import { $getNativeToolCallExampleString, coerceToArray, jsonToolResultSchema } from '../utils'
+
+import type { $ToolParams } from '../../constants'
+
+export const fileContentsSchema = z.union([
+  z.object({
+    path: z.string(),
+    content: z.string(),
+    referencedBy: z.record(z.string(), z.string().array()).optional(),
+  }),
+  z.object({
+    path: z.string(),
+    contentOmittedForLength: z.literal(true),
+  }),
+])
+
+const toolName = 'read_files'
+const endsAgentStep = true
+
+const pathEntrySchema = z
+  .string()
+  .min(1, 'Paths cannot be empty')
+  .describe(
+    `File path to read. Prefer paths relative to the **project root**; absolute paths inside the project are accepted, but paths outside the project will not work.`,
+  )
+
+const windowedEntrySchema = z.union([
+  pathEntrySchema,
+  z.object({
+    path: z.string().min(1, 'Paths cannot be empty'),
+    offset: z
+      .number()
+      .int()
+      .min(1)
+      .optional()
+      .describe('Line number to start reading from (1-indexed).'),
+    limit: z
+      .number()
+      .int()
+      .positive()
+      .optional()
+      .describe('Maximum number of lines to read (defaults to 2,000).'),
+  }),
+])
+
+const legacyInputSchema = z
+  .object({
+    paths: z
+      .preprocess(coerceToArray, z.array(pathEntrySchema))
+      .describe('List of file paths to read.'),
+  })
+  .describe(
+    `Read multiple files from disk. Returned file content shares a 20,000 estimated-token limit and a 100,000-character hard limit. Prefer the smallest relevant set of files and use code_search for targeted discovery.`,
+  )
+
+const windowedInputSchema = z
+  .object({
+    paths: z
+      .preprocess(coerceToArray, z.array(windowedEntrySchema))
+      .describe(
+        'List of files to read. Each entry is either a file path, or an object { path, offset, limit } to read a specific line range of that file.',
+      ),
+  })
+  .describe(
+    `Read files from disk. List several paths to read several files in one call. Large files are cut off after 2,000 lines, with a note telling you the file's total line count. Don't read a large file whole: use code_search to locate the part you need (matches come with line numbers), then read a window around it with { path, offset, limit }. Avoid tiny repeated slices; when in doubt, take a window of a few hundred lines.`,
+  )
+
+const description = `
+Example:
+${$getNativeToolCallExampleString({
+  toolName,
+  inputSchema: legacyInputSchema,
+  input: {
+    paths: ['path/to/file1.ts', 'path/to/file2.ts'],
+  },
+  endsAgentStep,
+})}
+`.trim()
+
+export const readFilesDisplayVariants = {
+  legacy: { description, inputSchema: legacyInputSchema },
+  windowed: { description, inputSchema: windowedInputSchema },
+}
+
+export function readFilePathsOf(paths: unknown): string[] {
+  if (!Array.isArray(paths)) return []
+  const result: string[] = []
+  for (const entry of paths) {
+    const path =
+      typeof entry === 'string'
+        ? entry
+        : entry && typeof entry === 'object' && typeof entry.path === 'string'
+          ? entry.path
+          : undefined
+    const trimmed = path?.trim()
+    if (trimmed) result.push(trimmed)
+  }
+  return result
+}
+
+export const readFilesParams = {
+  toolName,
+  endsAgentStep,
+  description,
+  inputSchema: windowedInputSchema,
+  outputSchema: jsonToolResultSchema(fileContentsSchema.array()),
+} satisfies $ToolParams

package/vendor/@anvil/common/src/tools/params/tool/read-subtree.ts

@@ -0,0 +1,79 @@
+import z from 'zod/v4'
+
+import { $getNativeToolCallExampleString, coerceToArray, jsonToolResultSchema } from '../utils'
+
+import type { $ToolParams } from '../../constants'
+
+const toolName = 'read_subtree'
+const endsAgentStep = true
+const inputSchema = z
+  .object({
+    paths: z
+      .preprocess(coerceToArray, z.array(z.string()))
+      .optional()
+      .describe(
+        `List of paths to directories or files. Relative to the project root. If omitted, the entire project tree is used.`,
+      ),
+    maxTokens: z
+      .number()
+      .int()
+      .positive()
+      .default(4000)
+      .describe(
+        `Maximum token budget for the subtree blob; the tree will be truncated to fit within this budget by first dropping file variables and then removing the most-nested files and directories.`,
+      ),
+  })
+  .describe(
+    `Read one or more directory subtrees (as a blob including subdirectories, file names, and parsed variables within each source file) or return parsed variable names for files. If no paths are provided, returns the entire project tree.`,
+  )
+const description = `
+Example:
+${$getNativeToolCallExampleString({
+  toolName,
+  inputSchema,
+  input: {
+    paths: ['src', 'package.json'],
+    maxTokens: 4000,
+  },
+  endsAgentStep,
+})}
+
+Purpose: Read a directory subtree and return a blob containing subdirectories, file names, and parsed variable/functions names from source files. For files, return only the parsed variable names. If no paths are provided, returns the entire project tree. The output is truncated to fit within the provided token budget.
+
+- Use this tool on particular subdirectories when you need to know all the nested files and directories. E.g. for a refactoring task, or to understand a particular part of the codebase.
+- In normal use, don't set maxTokens beyond 10,000.
+`.trim()
+
+export const readSubtreeParams = {
+  toolName,
+  endsAgentStep,
+  description,
+  inputSchema,
+  outputSchema: jsonToolResultSchema(
+    z.array(
+      z.union([
+        z.object({
+          path: z.string(),
+          type: z.literal('directory'),
+          printedTree: z.string(),
+          tokenCount: z.number(),
+          truncationLevel: z.enum([
+            'none',
+            'unimportant-files',
+            'tokens',
+            'depth-based',
+          ]),
+        }),
+        z.object({
+          path: z.string(),
+          type: z.literal('file'),
+          variables: z.array(z.string()),
+        }),
+        z.object({
+          path: z.string(),
+          errorMessage: z.string(),
+        }),
+      ]),
+    ),
+  ),
+} satisfies $ToolParams

package/vendor/@anvil/common/src/tools/params/tool/read-url.ts

@@ -0,0 +1,81 @@
+import z from 'zod/v4'
+
+import { $getNativeToolCallExampleString, jsonToolResultSchema } from '../utils'
+
+import type { $ToolParams } from '../../constants'
+
+const toolName = 'read_url'
+const endsAgentStep = true
+const inputSchema = z
+  .object({
+    url: z
+      .url()
+      .refine((value) => {
+        try {
+          const parsedUrl = new URL(value)
+          return (
+            parsedUrl.protocol === 'http:' || parsedUrl.protocol === 'https:'
+          )
+        } catch {
+          return false
+        }
+      }, 'URL must use http:// or https://')
+      .describe(
+        'The full http:// or https:// URL to fetch and extract readable text from.',
+      ),
+    max_chars: z
+      .number()
+      .int()
+      .min(1_000)
+      .max(50_000)
+      .default(20_000)
+      .optional()
+      .describe(
+        'Maximum number of extracted text characters to return. Defaults to 20000.',
+      ),
+  })
+  .describe('Fetch a URL and extract readable text from the page.')
+
+const description = `
+Purpose: Fetch a URL returned by web_search and extract the readable page text so you can answer with source-backed evidence.
+
+Use this after web_search when snippets are not enough. Prefer authoritative, relevant pages from the search results. The tool follows redirects, extracts titles and metadata, strips scripts/styles/navigation boilerplate from HTML, and returns normalized readable text.
+
+Do not use run_terminal_command with curl just to inspect web pages; use read_url instead. If read_url reports unsupported content or extraction failure, then choose a different search result or explain the limitation.
+
+Example:
+${$getNativeToolCallExampleString({
+  toolName,
+  inputSchema,
+  input: {
+    url: 'https://react.dev/reference/react/useActionState',
+    max_chars: 12000,
+  },
+  endsAgentStep,
+})}
+`.trim()
+
+export const readUrlParams = {
+  toolName,
+  endsAgentStep,
+  description,
+  inputSchema,
+  outputSchema: jsonToolResultSchema(
+    z.union([
+      z.object({
+        url: z.string(),
+        finalUrl: z.string(),
+        status: z.number(),
+        contentType: z.string().optional(),
+        title: z.string().optional(),
+        description: z.string().optional(),
+        text: z.string(),
+        truncated: z.boolean(),
+      }),
+      z.object({
+        url: z.string().optional(),
+        errorMessage: z.string(),
+      }),
+    ]),
+  ),
+} satisfies $ToolParams