@alumbwe/anvil 1.0.20 → 1.0.22

package/vendor/@anvil/common/src/tools/params/tool/code-search.ts

@@ -0,0 +1,159 @@
+import z from 'zod/v4'
+
+import { $getNativeToolCallExampleString, jsonToolResultSchema } from '../utils'
+
+import type { $ToolParams } from '../../constants'
+
+const toolName = 'code_search'
+const endsAgentStep = true
+const inputSchema = z
+  .object({
+    pattern: z
+      .string()
+      .min(1, 'Pattern cannot be empty')
+      .describe(`The pattern to search for.`),
+    flags: z
+      .string()
+      .optional()
+      .describe(
+        `Optional ripgrep flags to customize the search (e.g., "-i" for case-insensitive, "-g *.ts -g *.js" for TypeScript and JavaScript files only, "-g !*.test.ts" to exclude Typescript test files,  "-A 3" for 3 lines after match, "-B 2" for 2 lines before match).`,
+      ),
+    cwd: z
+      .string()
+      .optional()
+      .describe(
+        `Optional working directory to search within, relative to the project root. Defaults to searching the entire project.`,
+      ),
+    maxResults: z
+      .number()
+      .int()
+      .positive()
+      .optional()
+      .default(15)
+      .describe(
+        `Maximum number of results to return per file. Defaults to 15. There is also a global limit of 250 results across all files.`,
+      ),
+  })
+  .describe(
+    `Search for string patterns in the project's files. This tool uses ripgrep (rg), a fast line-oriented search tool.`,
+  )
+const legacyInputSchema = inputSchema.describe(
+  `Search for string patterns in the project's files. This tool uses ripgrep (rg), a fast line-oriented search tool. Use this tool only when read_files is not sufficient to find the files you need.`,
+)
+const buildDescription = (guidance: string) => `
+Purpose: Search through code files to find files with specific text patterns, function names, variable names, and more.
+
+${guidance}
+
+Use cases:
+1. Finding all references to a function, class, or variable name across the codebase
+2. Searching for specific code patterns or implementations
+3. Looking up where certain strings or text appear
+4. Finding files that contain specific imports or dependencies
+5. Locating configuration settings or environment variables
+
+The pattern supports regular expressions and will search recursively through all files in the project by default. Some tips:
+- Be as constraining in the pattern as possible to limit the number of files returned, e.g. if searching for the definition of a function, use "(function foo|const foo)" or "def foo" instead of merely "foo".
+- Use Rust-style regex, not grep-style, PCRE, RE2 or JavaScript regex - you must always escape special characters like { and }
+- Be as constraining as possible to limit results, e.g. use "(function foo|const foo)" or "def foo" instead of merely "foo"
+- Add context to your search with surrounding terms (e.g., "function handleAuth" rather than just "handleAuth")
+- Use word boundaries (\\b) to match whole words only
+- Use the cwd parameter to narrow your search to specific directories
+- For case-sensitive searches like constants (e.g., ERROR vs error), omit the "-i" flag
+- Searches file content and filenames
+- Automatically ignores binary files, hidden files, and files in .gitignore
+
+
+Advanced ripgrep flags (use the flags parameter):
+
+- Case sensitivity: "-i" for case-insensitive search
+- File type filtering: "-t ts -t js" (TypeScript and JavaScript), "-t py" (Python), etc.
+- Exclude file types: "--type-not py" to exclude Python files
+- Context lines: "-A 3" (3 lines after), "-B 2" (2 lines before), "-C 2" (2 lines before and after)
+- Line numbers: "-n" to show line numbers
+- Count matches: "-c" to count matches per file
+- Only filenames: "-l" to show only filenames with matches
+- Invert match: "-v" to show lines that don't match
+- Word boundaries: "-w" to match whole words only
+- Fixed strings: "-F" to treat pattern as literal string (not regex)
+
+Note: Do not use the end_turn tool after this tool! You will want to see the output of this tool before ending your turn.
+
+RESULT LIMITING:
+
+- The maxResults parameter limits the number of results shown per file (default: 15)
+- There is also a global limit of 250 total results across all files
+- These limits allow you to see results across multiple files without being overwhelmed by matches in a single file
+- If a file has more matches than maxResults, you'll see a truncation notice indicating how many results were found
+- If the global limit is reached, remaining files will be skipped
+
+Examples:
+${$getNativeToolCallExampleString({
+  toolName,
+  inputSchema,
+  input: { pattern: 'foo' },
+  endsAgentStep,
+})}
+${$getNativeToolCallExampleString({
+  toolName,
+  inputSchema,
+  input: { pattern: 'foo\\.bar = 1\\.0' },
+  endsAgentStep,
+})}
+${$getNativeToolCallExampleString({
+  toolName,
+  inputSchema,
+  input: { pattern: 'import.*foo', cwd: 'src' },
+  endsAgentStep,
+})}
+${$getNativeToolCallExampleString({
+  toolName,
+  inputSchema,
+  input: { pattern: 'function.*authenticate', flags: '-i -t ts -t js' },
+  endsAgentStep,
+})}
+${$getNativeToolCallExampleString({
+  toolName,
+  inputSchema,
+  input: { pattern: 'TODO', flags: '-n --type-not py' },
+  endsAgentStep,
+})}
+${$getNativeToolCallExampleString({
+  toolName,
+  inputSchema,
+  input: { pattern: 'getUserData', maxResults: 10 },
+  endsAgentStep,
+})}
+`.trim()
+
+const legacyDescription = buildDescription(
+  'Prefer to use read_files instead of code_search unless you need to search for a specific pattern in multiple files.',
+)
+const description = buildDescription(
+  'Matches are returned with their line numbers, so in a large file you can search first and then read a window around a match with read_files { path, offset, limit } instead of reading the whole file.',
+)
+
+export const codeSearchDisplayVariants = {
+  legacy: { description: legacyDescription, inputSchema: legacyInputSchema },
+  windowed: { description, inputSchema },
+}
+
+export const codeSearchParams = {
+  toolName,
+  endsAgentStep,
+  description,
+  inputSchema,
+  outputSchema: jsonToolResultSchema(
+    z.union([
+      z.object({
+        stdout: z.string(),
+        stderr: z.string().optional(),
+        exitCode: z.number().optional(),
+        message: z.string(),
+      }),
+      z.object({
+        errorMessage: z.string(),
+      }),
+    ]),
+  ),
+} satisfies $ToolParams

package/vendor/@anvil/common/src/tools/params/tool/composio.ts

@@ -0,0 +1,131 @@
+import { COMPOSIO_META_TOOL_NAMES } from '../../../constants/composio'
+import z from 'zod/v4'
+
+import { jsonToolResultSchema } from '../utils'
+
+import type { $ToolParams } from '../../constants'
+
+const sessionIdParam = z
+  .string()
+  .optional()
+  .describe('Session ID returned by composio_search_tools, when available.')
+
+const composioMetaToolInputSchemas = {
+  composio_search_tools: z
+    .object({
+      queries: z
+        .array(z.unknown())
+        .min(1)
+        .describe(
+          'Structured English search queries. Split independent app/API actions into separate queries.',
+        ),
+      session: z
+        .object({
+          generate_id: z.boolean().optional(),
+          id: z.string().optional(),
+        })
+        .catchall(z.unknown())
+        .describe(
+          'Use { generate_id: true } for a new workflow, or { id } to continue one.',
+        ),
+      model: z.string().optional().describe('Client LLM model name.'),
+    })
+    .catchall(z.unknown()),
+  composio_get_tool_schemas: z
+    .object({
+      tool_slugs: z
+        .array(z.string())
+        .min(1)
+        .describe('Composio tool slugs to retrieve schemas for.'),
+      include: z
+        .array(z.string())
+        .optional()
+        .describe('Schema fields to include, e.g. input_schema/output_schema.'),
+      session_id: sessionIdParam,
+    })
+    .catchall(z.unknown()),
+  composio_manage_connections: z
+    .object({
+      toolkits: z
+        .array(z.string())
+        .min(1)
+        .describe('Toolkit slugs to check or connect, such as gmail/github.'),
+      reinitiate_all: z
+        .boolean()
+        .optional()
+        .describe('Force reconnection even if active credentials exist.'),
+      session_id: sessionIdParam,
+    })
+    .catchall(z.unknown()),
+  composio_multi_execute_tool: z
+    .object({
+      tools: z
+        .array(z.record(z.string(), z.unknown()))
+        .min(1)
+        .describe('Logically independent Composio tools to execute.'),
+      thought: z
+        .string()
+        .optional()
+        .describe('One concise sentence explaining the execution intent.'),
+      sync_response_to_workbench: z
+        .boolean()
+        .default(false)
+        .describe('Always use false. Anvil disables Composio workbench.'),
+      session_id: sessionIdParam,
+    })
+    .catchall(z.unknown()),
+}
+
+const composioMetaToolDescriptions = {
+  composio_search_tools:
+    'Discover relevant Composio tools across external apps. Use this first for requests involving services like Gmail, GitHub, Slack, Linear, Notion, Google Calendar, or Google Sheets.',
+  composio_get_tool_schemas:
+    'Retrieve complete input schemas for specific Composio tool slugs returned by composio_search_tools.',
+  composio_manage_connections:
+    'Check or initiate user authentication for external app toolkits. Use when search/execution indicates a toolkit is not connected.',
+  composio_multi_execute_tool:
+    'Execute one or more discovered Composio app tools in the current workflow session. Do not use workbench offloading.',
+}
+
+const composioOutputSchema = jsonToolResultSchema(
+  z.union([
+    z.json(),
+    z.object({
+      errorMessage: z.string(),
+      status: z.number().optional(),
+    }),
+  ]),
+)
+
+export const composioMetaToolParams = {
+  composio_manage_connections: {
+    toolName: 'composio_manage_connections',
+    endsAgentStep: true,
+    description: composioMetaToolDescriptions.composio_manage_connections,
+    inputSchema: composioMetaToolInputSchemas.composio_manage_connections,
+    outputSchema: composioOutputSchema,
+  },
+  composio_multi_execute_tool: {
+    toolName: 'composio_multi_execute_tool',
+    endsAgentStep: true,
+    description: composioMetaToolDescriptions.composio_multi_execute_tool,
+    inputSchema: composioMetaToolInputSchemas.composio_multi_execute_tool,
+    outputSchema: composioOutputSchema,
+  },
+  composio_search_tools: {
+    toolName: 'composio_search_tools',
+    endsAgentStep: true,
+    description: composioMetaToolDescriptions.composio_search_tools,
+    inputSchema: composioMetaToolInputSchemas.composio_search_tools,
+    outputSchema: composioOutputSchema,
+  },
+  composio_get_tool_schemas: {
+    toolName: 'composio_get_tool_schemas',
+    endsAgentStep: true,
+    description: composioMetaToolDescriptions.composio_get_tool_schemas,
+    inputSchema: composioMetaToolInputSchemas.composio_get_tool_schemas,
+    outputSchema: composioOutputSchema,
+  },
+} satisfies {
+  [K in (typeof COMPOSIO_META_TOOL_NAMES)[number]]: $ToolParams<K>
+}

package/vendor/@anvil/common/src/tools/params/tool/create-plan.ts

@@ -0,0 +1,80 @@
+import z from 'zod/v4'
+
+import { updateFileResultSchema } from './str-replace'
+import { $getNativeToolCallExampleString, jsonToolResultSchema } from '../utils'
+
+import type { $ToolParams } from '../../constants'
+
+const toolName = 'create_plan'
+const endsAgentStep = false
+const inputSchema = z
+  .object({
+    path: z
+      .string()
+      .min(1, 'Path cannot be empty')
+      .describe(
+        `The path including the filename of a markdown file that will be overwritten with the plan.`,
+      ),
+    plan: z
+      .string()
+      .min(1, 'Plan cannot be empty')
+      .describe(`A detailed plan to solve the user's request.`),
+  })
+  .describe(`Generate a detailed markdown plan for complex tasks.`)
+const description = `
+Use when:
+- User explicitly requests a detailed plan.
+- Use this tool to overwrite a previous plan by using the exact same file name.
+
+Don't include:
+- Goals, timelines, benefits, next steps.
+- Background context or extensive explanations.
+
+For a technical plan, act as an expert architect engineer and provide direction to your editor engineer.
+- Study the change request and the current code.
+- Describe how to modify the code to complete the request. The editor engineer will rely solely on your instructions, so make them unambiguous and complete.
+- Explain all needed code changes clearly and completely, but concisely.
+- Just show the changes needed.
+
+What to include in the plan:
+- Include key snippets of code -- not full files of it. Use pseudo code. For example, include interfaces between modules, function signatures, and other code that is not immediately obvious should be written out explicitly. Function and method bodies could be written out in psuedo code.
+- Do not waste time on much background information, focus on the exact steps of the implementation.
+- Do not wrap the path content in markdown code blocks, e.g. \`\`\`.
+
+Do not include any of the following sections in the plan:
+- goals
+- a timeline or schedule
+- benefits/key improvements
+- next steps
+
+After creating the plan, you should end turn to let the user review the plan.
+
+Important: Use this tool sparingly. Do not use this tool more than once in a conversation, unless in ask mode.
+
+Examples:
+${$getNativeToolCallExampleString({
+  toolName,
+  inputSchema,
+  input: {
+    path: 'feature-x-plan.md',
+    plan: [
+      '1. Create module `auth.ts` in `/src/auth/`.',
+      '```ts',
+      'export function authenticate(user: User): boolean { /* pseudo-code logic */ }',
+      '```',
+      '2. Refactor existing auth logic into this module.',
+      '3. Update imports across codebase.',
+      '4. Write integration tests covering new module logic.',
+    ].join('\n'),
+  },
+  endsAgentStep,
+})}
+`.trim()
+
+export const createPlanParams = {
+  toolName,
+  endsAgentStep,
+  description,
+  inputSchema,
+  outputSchema: jsonToolResultSchema(updateFileResultSchema),
+} satisfies $ToolParams

package/vendor/@anvil/common/src/tools/params/tool/end-turn.ts

@@ -0,0 +1,57 @@
+import z from 'zod/v4'
+
+import {
+  $getNativeToolCallExampleString,
+  textToolResultSchema,
+} from '../utils'
+
+import type { $ToolParams } from '../../constants'
+
+const toolName = 'end_turn'
+const endsAgentStep = true
+const inputSchema = z
+  .object({})
+  .describe(
+    `End your turn, regardless of any new tool results that might be coming. This will allow the user to type another prompt.`,
+  )
+const description = `
+Only use this tool to hand control back to the user.
+
+- When to use: after you have completed a meaningful chunk of work and you are either (a) fully done, or (b) explicitly waiting for the user's next message.
+- Do NOT use: as a stop token mid-work, to pause between tool calls, to wait for tool results, or to "check in" unnecessarily.
+- Before calling: finish all pending steps, resolve tool results, and include any outputs the user needs to review.
+- Effect: Signals the UI to wait for the user's reply; any pending tool results will be ignored.
+
+*INCORRECT USAGE*:
+${$getNativeToolCallExampleString({
+  toolName: 'some_tool_that_produces_results',
+  inputSchema: null,
+  input: { query: 'some example search term' },
+  endsAgentStep: false,
+})}
+
+${$getNativeToolCallExampleString({
+  toolName,
+  inputSchema,
+  input: {},
+  endsAgentStep: true,
+})}
+
+*CORRECT USAGE*:
+All done! Would you like some more help with xyz?
+
+${$getNativeToolCallExampleString({
+  toolName,
+  inputSchema,
+  input: {},
+  endsAgentStep: false,
+})}
+`.trim()
+
+export const endTurnParams = {
+  toolName,
+  endsAgentStep,
+  description,
+  inputSchema,
+  outputSchema: textToolResultSchema(),
+} satisfies $ToolParams

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

@@ -0,0 +1,60 @@
+import z from 'zod/v4'
+
+import { fileContentsSchema } from './read-files'
+import { $getNativeToolCallExampleString, jsonToolResultSchema } from '../utils'
+
+import type { $ToolParams } from '../../constants'
+
+const toolName = 'find_files'
+const endsAgentStep = true
+const inputSchema = z
+  .object({
+    prompt: z
+      .string()
+      .min(1, 'Prompt cannot be empty')
+      .describe(
+        `A brief natural language description of the files or the name of a function or class you are looking for. It's also helpful to mention a directory or two to look within.`,
+      ),
+  })
+  .describe(
+    `Find several files related to a brief natural language description of the files or the name of a function or class you are looking for.`,
+  )
+const description = `
+Example:
+${$getNativeToolCallExampleString({
+  toolName,
+  inputSchema,
+  input: {
+    prompt: 'The implementation of function foo',
+  },
+  endsAgentStep,
+})}
+
+Purpose: Better fulfill the user request by reading files which could contain information relevant to the user's request.
+Use cases:
+- If you are calling a function or creating a class and want to know how it works, use this tool to get the implementation.
+- If you need to understand a section of the codebase, read more files in that directory or subdirectories.
+- Some requests require a broad understanding of multiple parts of the codebase. Consider using find_files to gain more context before making changes.
+
+Don't use this tool if:
+- You already know the exact path of the file(s) you are looking for — in this case, use read_files.
+- You already read the files you need in context.
+- You know the name of the file you need. Instead use run_terminal_command with \`find -name\` (or \`dir /s /b\` or \`Get-ChildItem -Recurse -Filter\`)
+
+This tool is not guaranteed to find the correct file. In general, prefer using read_files instead of find_files.
+`.trim()
+
+export const findFilesParams = {
+  toolName,
+  endsAgentStep,
+  description,
+  inputSchema,
+  outputSchema: jsonToolResultSchema(
+    z.union([
+      fileContentsSchema.array(),
+      z.object({
+        message: z.string(),
+      }),
+    ]),
+  ),
+} satisfies $ToolParams

package/vendor/@anvil/common/src/tools/params/tool/glob.ts

@@ -0,0 +1,80 @@
+import z from 'zod/v4'
+
+import { $getNativeToolCallExampleString, jsonToolResultSchema } from '../utils'
+
+import type { $ToolParams } from '../../constants'
+
+const toolName = 'glob'
+const endsAgentStep = false
+const inputSchema = z
+  .object({
+    pattern: z
+      .string()
+      .min(1, 'Pattern cannot be empty')
+      .describe(
+        'Glob pattern to match files against (e.g., *.js, src/glob/*.ts, glob/test/glob/*.go).',
+      ),
+    cwd: z
+      .string()
+      .optional()
+      .describe(
+        'Optional working directory to search within, relative to project root. If not provided, searches from project root.',
+      ),
+    max_results: z
+      .number()
+      .int()
+      .positive()
+      .optional()
+      .describe('Maximum number of matching paths to return.'),
+  })
+  .describe(
+    `Search for files matching a glob pattern. Returns matching file paths sorted by modification time.`,
+  )
+const description = `
+Example:
+${$getNativeToolCallExampleString({
+  toolName,
+  inputSchema,
+  input: {
+    pattern: '**/*.test.ts',
+  },
+  endsAgentStep,
+})}
+
+Purpose: Search for files matching a glob pattern to discover files by name patterns rather than content.
+Use cases:
+- Find all files with a specific extension (e.g., "*.js", "*.test.ts")
+- Locate files in specific directories (e.g., "src/**/*.ts")
+- Find files with specific naming patterns (e.g., "**/test_*.go", "**/*-config.json")
+- Discover test files, configuration files, or other files with predictable naming
+
+Glob patterns support:
+- * matches any characters except /
+- ** matches any characters including /
+- ? matches a single character
+- [abc] matches one of the characters in brackets
+- {a,b} matches one of the comma-separated patterns
+
+This tool is fast and works well for discovering files by name patterns.
+`.trim()
+
+export const globParams = {
+  toolName,
+  description,
+  endsAgentStep,
+  inputSchema,
+  outputSchema: jsonToolResultSchema(
+    z.union([
+      z.object({
+        files: z.array(z.string()).describe('Array of matching file paths'),
+        count: z
+          .number()
+          .describe('Total number of files matching the pattern'),
+        message: z.string().describe('Success message'),
+      }),
+      z.object({
+        errorMessage: z.string().describe('Error message if search failed'),
+      }),
+    ]),
+  ),
+} satisfies $ToolParams

package/vendor/@anvil/common/src/tools/params/tool/gravity-index.ts

@@ -0,0 +1,93 @@
+import z from 'zod/v4'
+
+import { gravityIndexInputSchema } from '../../../types/gravity-index'
+import { $getNativeToolCallExampleString, jsonToolResultSchema } from '../utils'
+import { jsonObjectSchema } from '../../../types/json'
+
+import type { $ToolParams } from '../../constants'
+
+const toolName = 'gravity_index'
+const endsAgentStep = true
+
+const description = `
+Purpose: Use the Gravity Index to discover, inspect, and report integrations for third-party developer services such as databases, auth, payments, hosting, email, cache, monitoring, analytics, AI, storage, CMS, search, realtime, background jobs, infrastructure, CRM, support, productivity, commerce, video, webhooks, and SMS.
+
+Choose the action:
+- \`search\`: Use when the user asks for a recommendation or when you need to choose a provider before integrating it. Returns a reasoned recommendation with install guidance, env vars, and a setup/conversion URL. Include stack and constraints in \`query\`. Pass \`search_id\` from a previous search for follow-up questions.
+- \`browse\`: Use to list catalog services by \`category\` and/or keyword \`q\`. Good when the user wants options or a category-scoped picker.
+- \`list_categories\`: Use to see available categories and service counts.
+- \`get_service\`: Use when you already know a service slug and need full detail, env vars, website, docs URL, and install metadata.
+- \`report_integration\`: Use after you have actually completed and verified an integration from a previous search. Pass the original \`search_id\` and the service slug as \`integrated_slug\`.
+
+Important setup-link behavior:
+- Search results may include \`credential_request.setup_url\`, \`recommendation.click_url\`, and/or top-level \`click_url\`, the tracked setup link the user should visit to create an account and get API credentials.
+- A search can contain a recommendation and several options, and you may search more than once. Decide which single service you are actually recommending before rendering a CTA.
+- When \`render_ui\` is available, call it once for the selected service. Use a gravity_index link reference with the exact \`search_id\` and selected \`service_slug\`; never transcribe the opaque URL. The runtime verifies the selection and substitutes the exact stored click URL.
+- When \`render_ui\` is unavailable, preserve and present the exact returned tracked URL in a normal markdown link.
+- Do not replace the tracked setup link with the vendor homepage and do not auto-follow it.
+- Ask the user to paste the required env vars from \`credential_request.required_env_vars\` back so you can finish setup.
+
+Implementation guidance:
+- Gravity returns reasoning, \`install.steps\`, \`install.env_vars\`, and \`credential_request\`. Execute the install steps you can perform locally, then pause only for missing user credentials.
+- Use the returned \`docs_url\`, existing codebase conventions, and package/docs research to fill any gaps in the install instructions.
+- For browsing results, use \`get_service\` on promising slugs before making a final recommendation if details matter.
+
+Examples:
+${$getNativeToolCallExampleString({
+  toolName,
+  inputSchema: gravityIndexInputSchema,
+  input: {
+    action: 'search',
+    query:
+      'transactional email API with a generous free tier for a Next.js app',
+  },
+  endsAgentStep,
+})}
+
+${$getNativeToolCallExampleString({
+  toolName,
+  inputSchema: gravityIndexInputSchema,
+  input: {
+    action: 'browse',
+    category: 'Email',
+    q: 'send',
+  },
+  endsAgentStep,
+})}
+
+${$getNativeToolCallExampleString({
+  toolName,
+  inputSchema: gravityIndexInputSchema,
+  input: {
+    action: 'get_service',
+    slug: 'sendgrid',
+  },
+  endsAgentStep,
+})}
+
+${$getNativeToolCallExampleString({
+  toolName,
+  inputSchema: gravityIndexInputSchema,
+  input: {
+    action: 'report_integration',
+    search_id: 'search_id_from_previous_search',
+    integrated_slug: 'sendgrid',
+  },
+  endsAgentStep,
+})}
+`.trim()
+
+export const gravityIndexParams = {
+  toolName,
+  endsAgentStep,
+  description,
+  inputSchema: gravityIndexInputSchema,
+  outputSchema: jsonToolResultSchema(
+    z.union([
+      jsonObjectSchema,
+      z.object({
+        errorMessage: z.string(),
+      }),
+    ]),
+  ),
+} satisfies $ToolParams