@alumbwe/anvil 1.0.20 → 1.0.21

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

@@ -0,0 +1,59 @@
+import z from 'zod/v4'
+
+import { $getNativeToolCallExampleString, jsonToolResultSchema } from '../utils'
+
+import type { $ToolParams } from '../../constants'
+
+const toolName = 'skill'
+const endsAgentStep = true
+
+const inputSchema = z
+  .object({
+    name: z
+      .string()
+      .min(1)
+      .describe('The name of the skill to load'),
+  })
+  .describe(
+    'Load a skill by name to get its full instructions. Skills provide reusable behaviors and instructions.',
+  )
+
+const outputValueSchema = z.object({
+  name: z.string(),
+  description: z.string(),
+  content: z.string(),
+  license: z.string().optional(),
+})
+
+/**
+ * Placeholder marker that will be replaced with the actual available skills XML.
+ * This is replaced at runtime when generating tool prompts.
+ */
+export const AVAILABLE_SKILLS_PLACEHOLDER = '{{AVAILABLE_SKILLS}}'
+
+// Base description - the full description with available skills is generated dynamically
+const baseDescription = `Load a skill by name to get its full instructions. Skills provide reusable behaviors and domain-specific knowledge that you can use to complete tasks.
+
+The following are the pre-loaded skills available at session start:
+${AVAILABLE_SKILLS_PLACEHOLDER}
+
+Note: You can load any skill by name, including ones created or installed during this session (e.g. via \`npx skills add\`). The skill is always read fresh from disk, so its latest contents are used.
+
+Example:
+${$getNativeToolCallExampleString({
+  toolName,
+  inputSchema,
+  input: {
+    name: 'git-release',
+  },
+  endsAgentStep,
+})}
+`
+
+export const skillParams = {
+  toolName,
+  endsAgentStep,
+  description: baseDescription.trim(),
+  inputSchema,
+  outputSchema: jsonToolResultSchema(outputValueSchema),
+} satisfies $ToolParams

package/vendor/@anvil/common/src/tools/params/tool/spawn-agent-inline.ts

@@ -0,0 +1,56 @@
+import z from 'zod/v4'
+
+import {
+  $getNativeToolCallExampleString,
+  coerceToObject,
+  textToolResultSchema,
+} from '../utils'
+
+import type { $ToolParams } from '../../constants'
+
+const toolName = 'spawn_agent_inline'
+const endsAgentStep = true
+const inputSchema = z
+  .object({
+    agent_type: z.string().describe('Agent to spawn'),
+    prompt: z.string().optional().describe('Prompt to send to the agent'),
+    params: z
+      .preprocess(coerceToObject, z.record(z.string(), z.any()))
+      .optional()
+      .describe('Parameters object for the agent (if any)'),
+  })
+  .describe(
+    `Spawn a single agent that runs within the current message history.`,
+  )
+const description = `
+Spawn a single agent that runs within the current message history. 
+The spawned agent sees all previous messages and any messages it adds 
+are preserved when control returns to you.
+
+You should prefer to use the spawn_agents tool unless instructed otherwise. This tool is only for special cases.
+
+This is useful for:
+- Delegating specific tasks while maintaining context
+- Having specialized agents process information inline
+- Managing message history (e.g., summarization)
+The agent will run until it calls end_turn, then control returns to you. There is no tool result for this tool.
+Example:
+${$getNativeToolCallExampleString({
+  toolName,
+  inputSchema,
+  input: {
+    agent_type: 'file-picker',
+    prompt: 'Find files related to authentication',
+    params: { paths: ['src/auth.ts', 'src/user.ts'] },
+  },
+  endsAgentStep,
+})}
+`.trim()
+
+export const spawnAgentInlineParams = {
+  toolName,
+  endsAgentStep,
+  description,
+  inputSchema,
+  outputSchema: textToolResultSchema(),
+} satisfies $ToolParams

package/vendor/@anvil/common/src/tools/params/tool/spawn-agents.ts

@@ -0,0 +1,154 @@
+import z from 'zod/v4'
+
+import { jsonObjectSchema } from '../../../types/json'
+import {
+  $getNativeToolCallExampleString,
+  coerceToArray,
+  coerceToObject,
+  jsonToolResultSchema,
+} from '../utils'
+
+import type { $ToolParams } from '../../constants'
+
+export const spawnAgentsOutputSchema = z
+  .object({
+    agentType: z.string(),
+  })
+  .and(jsonObjectSchema)
+  .array()
+
+const toolName = 'spawn_agents'
+const endsAgentStep = true
+const inputSchema = z
+  .object({
+    agents: z.preprocess(
+      coerceToArray,
+      z
+        .object({
+          agent_type: z.string().describe('Agent to spawn'),
+          prompt: z.string().optional().describe('Prompt to send to the agent'),
+          params: z
+            .preprocess(
+              coerceToObject,
+              z
+                .object({
+                  // Common agent fields (all optional hints — each agent validates its own required fields)
+                  command: z
+                    .string()
+                    .optional()
+                    .describe('Terminal command to run (basher, tmux-cli)'),
+                  what_to_summarize: z
+                    .string()
+                    .optional()
+                    .describe(
+                      'What information from the command output is desired (basher)',
+                    ),
+                  timeout_seconds: z
+                    .number()
+                    .optional()
+                    .describe(
+                      'Timeout for command. Set to -1 for no timeout. Default 30 (basher)',
+                    ),
+                  searchQueries: z
+                    .array(
+                      z.object({
+                        pattern: z
+                          .string()
+                          .describe('The pattern to search for'),
+                        flags: z
+                          .string()
+                          .optional()
+                          .describe(
+                            'Optional ripgrep flags (e.g., "-i", "-g *.ts")',
+                          ),
+                        cwd: z
+                          .string()
+                          .optional()
+                          .describe(
+                            'Optional working directory relative to project root',
+                          ),
+                        maxResults: z
+                          .number()
+                          .optional()
+                          .describe('Max results per file. Default 15'),
+                      }),
+                    )
+                    .optional()
+                    .describe('Array of code search queries (code-searcher)'),
+                  filePaths: z
+                    .array(z.string())
+                    .optional()
+                    .describe(
+                      'Relevant file paths to read (opus-agent, gpt-5-agent)',
+                    ),
+                  directories: z
+                    .array(z.string())
+                    .optional()
+                    .describe('Directories to search within (file-picker)'),
+                  url: z
+                    .string()
+                    .optional()
+                    .describe('Starting URL to navigate to (browser-use)'),
+                  prompts: z
+                    .array(z.string())
+                    .optional()
+                    .describe(
+                      'Array of strategy prompts (editor-multi-prompt, code-reviewer-multi-prompt)',
+                    ),
+                })
+                .catchall(z.any()),
+            )
+            .optional()
+            .describe('Parameters object for the agent'),
+        })
+        .array(),
+    ),
+  })
+  .describe(
+    `Spawn multiple agents and send a prompt and/or parameters to each of them. These agents will run in parallel. Note that that means they will run independently. If you need to run agents sequentially, use spawn_agents with one agent at a time instead.`,
+  )
+const description = `
+Use this tool to spawn agents to help you complete the user request. Each agent has specific requirements for prompt and params based on their tools schema.
+
+The prompt field is a simple string, while params is a JSON object that gets validated against the agent's schema.
+
+Each agent available is already defined as another tool, or, dynamically defined later in the conversation.
+
+**IMPORTANT**: \`agent_type\` must be an actual agent name (e.g., \`basher\`, \`code-searcher\`, \`opus-agent\`), NOT a tool name like \`read_files\`, \`str_replace\`, \`code_search\`, etc. If you need to call a tool, use it directly as a tool call instead of wrapping it in spawn_agents.
+
+You can call agents either as direct tool calls (using the listed tool name, e.g. \`example_agent\`) or use \`spawn_agents\` with the canonical agent name in \`agent_type\` (e.g. \`example-agent\`). Both formats work, but **prefer using spawn_agents** because it allows you to spawn multiple agents in parallel for better performance. Both use the same schema with nested \`prompt\` and \`params\` fields.
+
+**IMPORTANT**: Many agents have REQUIRED fields in their params schema. Check the agent's schema before spawning - if params has required fields, you MUST include them in the params object. For example, code-searcher requires \`searchQueries\`, basher requires \`command\`.
+
+Example:
+${$getNativeToolCallExampleString({
+  toolName,
+  inputSchema,
+  input: {
+    agents: [
+      {
+        agent_type: 'basher',
+        prompt: 'Check if tests pass',
+        params: {
+          command: 'npm test',
+        },
+      },
+      {
+        agent_type: 'code-searcher',
+        params: {
+          searchQueries: [{ pattern: 'authenticate', flags: '-g *.ts' }],
+        },
+      },
+    ],
+  },
+  endsAgentStep,
+})}
+`.trim()
+
+export const spawnAgentsParams = {
+  toolName,
+  endsAgentStep,
+  description,
+  inputSchema,
+  outputSchema: jsonToolResultSchema(spawnAgentsOutputSchema),
+} satisfies $ToolParams

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

@@ -0,0 +1,107 @@
+import z from 'zod/v4'
+
+import {
+  $getNativeToolCallExampleString,
+  coerceToArray,
+  jsonToolResultSchema,
+  normalizeReplacementAliases,
+} from '../utils'
+
+import type { $ToolParams } from '../../constants'
+
+export const updateFileResultSchema = z.union([
+  z.object({
+    file: z.string(),
+    message: z.string(),
+  }),
+  z.object({
+    file: z.string(),
+    errorMessage: z.string(),
+    patch: z.string().optional(),
+  }),
+])
+
+const toolName = '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(`Replace strings in a file with new strings.`)
+const description = `
+Use this tool to make edits within existing files.
+
+Important:
+If you are making multiple edits in a row to a file, use only one str_replace call with multiple replacements instead of multiple str_replace tool calls.
+
+Example:
+${$getNativeToolCallExampleString({
+  toolName,
+  inputSchema,
+  input: {
+    path: 'path/to/file',
+    replacements: [
+      {
+        oldString: 'This is the old string',
+        newString: 'This is the new string',
+      },
+      {
+        oldString:
+          '\n\t\t// @anvil delete this log line please\n\t\tconsole.log("Hello, world!");\n',
+        newString: '\n',
+      },
+      {
+        oldString: '\nfoo:',
+        newString: '\nbar:',
+        allowMultiple: true,
+      },
+    ],
+  },
+  endsAgentStep,
+})}
+    `.trim()
+
+export const strReplaceParams = {
+  toolName,
+  endsAgentStep,
+  description,
+  inputSchema,
+  outputSchema: jsonToolResultSchema(updateFileResultSchema),
+} satisfies $ToolParams

package/vendor/@anvil/common/src/tools/params/tool/suggest-followups.ts

@@ -0,0 +1,97 @@
+import z from 'zod/v4'
+
+import { $getNativeToolCallExampleString, coerceToArray, jsonToolResultSchema } from '../utils'
+
+import type { $ToolParams } from '../../constants'
+
+const toolName = 'suggest_followups'
+const endsAgentStep = false
+
+const followupSchema = z.object({
+  prompt: z
+    .string()
+    .describe(
+      'The prompt text to send as a user message when clicked. Keep it short and goal-oriented — one sentence naming the outcome, not the steps to get there',
+    ),
+  label: z
+    .string()
+    .optional()
+    .describe(
+      'Short display label for the card (defaults to truncated prompt if not provided)',
+    ),
+})
+
+export type SuggestFollowup = z.infer<typeof followupSchema>
+
+const inputSchema = z
+  .object({
+    followups: z
+      .preprocess(
+        coerceToArray,
+        z
+          .array(followupSchema)
+          .min(1, 'Must provide at least one followup'),
+      )
+      .describe(
+        'List of suggested followup prompts the user can click to send',
+      ),
+  })
+  .describe(
+    `Suggest clickable followup prompts to the user. Each followup becomes a card the user can click to send that prompt.`,
+  )
+
+const outputSchema = z.object({
+  message: z.string(),
+})
+
+const description = `
+Suggest clickable followup prompts to the user. When the user clicks a suggestion, it sends that prompt as a new user message.
+
+Use this tool after completing a task to suggest what the user might want to do next. Good suggestions include:
+- Alternatives to the latest implementation like "Cache the data in local storage instead"
+- Related features like "Show the state data in a hover card"
+- Cleanup opportunities like "Split app.ts into focused modules"
+- Testing suggestions like "Add unit tests for this change"
+- Verification you can run yourself like "Check the login flow in the browser and fix what breaks"
+- "Continue with the next step" - when there are more steps in a plan
+
+Keep every suggestion short and goal-oriented: one sentence naming the outcome you want, not the steps to get there. Whoever picks up the prompt does better work when free to choose the approach, so leave out file paths, function names, ordering, and design decisions unless one of those is the actual point of the request. A prompt still has to stand on its own — name the target clearly, just don't narrate a plan.
+
+Don't include suggestions like:
+- "Commit these changes"
+- Anything the user would have to carry out themselves, like "Ask your designer whether this matches the spec" — as opposed to "Add test coverage for the login flow", which is a goal the assistant can own. Judge by the tools you actually have: work you can do yourself is a goal, not a chore.
+
+Try to make different suggestions than you did in past steps. That's because users can still click previous suggestions if they want to.
+
+Aim for around 3 suggestions. The suggestions persist and remain clickable, with clicked ones visually updated to show they were used.
+
+${$getNativeToolCallExampleString({
+  toolName,
+  inputSchema,
+  input: {
+    followups: [
+      {
+        prompt: 'Continue with the next step',
+        label: 'Continue',
+      },
+      {
+        prompt: 'Add unit tests for UserService',
+        label: 'Add tests',
+      },
+      {
+        prompt: 'Pull the auth logic out of the request handler',
+        label: 'Refactor auth',
+      },
+    ],
+  },
+  endsAgentStep,
+})}
+`.trim()
+
+export const suggestFollowupsParams = {
+  toolName,
+  endsAgentStep,
+  description,
+  inputSchema,
+  outputSchema: jsonToolResultSchema(outputSchema),
+} satisfies $ToolParams

package/vendor/@anvil/common/src/tools/params/tool/task-completed.ts

@@ -0,0 +1,61 @@
+import z from 'zod/v4'
+
+import {
+  $getNativeToolCallExampleString,
+  textToolResultSchema,
+} from '../utils'
+
+import type { $ToolParams } from '../../constants'
+
+const toolName = 'task_completed'
+const endsAgentStep = true
+const inputSchema = z.object({}).describe(
+  `Signal that the task is complete. Use this tool when:
+- The user's request is completely fulfilled
+- You need clarification from the user before continuing
+- You are stuck or need help from the user to continue
+
+This tool explicitly marks the end of your work on the current task.`,
+)
+const description = `
+Use this tool to signal that the task is complete.
+
+- When to use:
+  * The user's request is completely fulfilled and you have nothing more to do
+  * You need clarification from the user before continuing
+  * You need help from the user to continue (e.g., missing information, unclear requirements)
+  * You've encountered a blocker that requires user intervention
+
+- Before calling:
+  * Ensure all pending work is finished
+  * Resolve all tool results
+  * Provide any outputs or summaries the user needs
+
+- Effect: Signals completion of the current task and returns control to the user
+
+*EXAMPLE USAGE*:
+
+All changes have been implemented and tested successfully!
+
+${$getNativeToolCallExampleString({ toolName, inputSchema, input: {}, endsAgentStep })}
+
+OR
+
+I need more information to proceed. Which database schema should I use for this migration?
+
+${$getNativeToolCallExampleString({ toolName, inputSchema, input: {}, endsAgentStep })}
+
+OR
+
+I can't get the tests to pass after several different attempts. I need help from the user to proceed.
+
+${$getNativeToolCallExampleString({ toolName, inputSchema, input: {}, endsAgentStep })}
+`.trim()
+
+export const taskCompletedParams = {
+  toolName,
+  endsAgentStep,
+  description,
+  inputSchema,
+  outputSchema: textToolResultSchema(),
+} satisfies $ToolParams

package/vendor/@anvil/common/src/tools/params/tool/think-deeply.ts

@@ -0,0 +1,56 @@
+import z from 'zod/v4'
+
+import {
+  $getNativeToolCallExampleString,
+  textToolResultSchema,
+} from '../utils'
+
+import type { $ToolParams } from '../../constants'
+
+const toolName = 'think_deeply'
+const endsAgentStep = false
+const inputSchema = z
+  .object({
+    thought: z
+      .string()
+      .min(1, 'Thought cannot be empty')
+      .describe(
+        `Detailed step-by-step analysis. Initially keep each step concise (max ~5-7 words per step).`,
+      ),
+  })
+  .describe(
+    `Deeply consider complex tasks by brainstorming approaches and tradeoffs step-by-step.`,
+  )
+const description = `
+Use when user request:
+- Explicitly asks for deep planning.
+- Requires multi-file changes or complex logic.
+- Involves significant architecture or potential edge cases.
+
+Avoid for simple changes (e.g., single functions, minor edits).
+
+This tool does not generate a tool result.
+
+Example:
+${$getNativeToolCallExampleString({
+  toolName,
+  inputSchema,
+  input: {
+    thought: [
+      '1. Check current user authentication',
+      '2. Refactor auth logic into module',
+      '3. Update imports across project',
+      '4. Add tests for new module',
+    ].join('\n'),
+  },
+  endsAgentStep,
+})}
+`.trim()
+
+export const thinkDeeplyParams = {
+  toolName,
+  endsAgentStep,
+  description,
+  inputSchema,
+  outputSchema: textToolResultSchema(),
+} satisfies $ToolParams

package/vendor/@anvil/common/src/tools/params/tool/update-subgoal.ts

@@ -0,0 +1,89 @@
+import z from 'zod/v4'
+
+import { $getNativeToolCallExampleString, jsonToolResultSchema } from '../utils'
+
+import type { $ToolParams } from '../../constants'
+
+const toolName = 'update_subgoal'
+const endsAgentStep = false
+const inputSchema = z
+  .object({
+    id: z
+      .string()
+      .min(1, 'Id cannot be empty')
+      .describe(`The id of the subgoal to update.`),
+    status: z
+      .enum(['NOT_STARTED', 'IN_PROGRESS', 'COMPLETE', 'ABORTED'])
+      .optional()
+      .describe(`Change the status of the subgoal.`),
+    plan: z.string().optional().describe(`Change the plan for the subgoal.`),
+    log: z
+      .string()
+      .optional()
+      .describe(
+        `Add a log message to the subgoal. This will create a new log entry and append it to the existing logs. Use this to record your progress and any new information you learned as you go.`,
+      ),
+  })
+  .describe(
+    `Update a subgoal in the context given the id, and optionally the status or plan, or a new log to append. Feel free to update any combination of the status, plan, or log in one invocation.`,
+  )
+const description = `
+Examples:
+
+Usage 1 (update status):
+${$getNativeToolCallExampleString({
+  toolName,
+  inputSchema,
+  input: {
+    id: '1',
+    status: 'COMPLETE',
+  },
+  endsAgentStep,
+})}
+
+Usage 2 (update plan):
+${$getNativeToolCallExampleString({
+  toolName,
+  inputSchema,
+  input: {
+    id: '3',
+    plan: 'Create file for endpoint in the api. Register it in the router.',
+  },
+  endsAgentStep,
+})}
+
+Usage 3 (add log):
+${$getNativeToolCallExampleString({
+  toolName,
+  inputSchema,
+  input: {
+    id: '1',
+    log: 'Found the error in the tests. Culprit: foo function.',
+  },
+  endsAgentStep,
+})}
+
+Usage 4 (update status and add log):
+${$getNativeToolCallExampleString({
+  toolName,
+  inputSchema,
+  input: {
+    id: '1',
+    status: 'COMPLETE',
+    log: 'Reran the tests (passed)',
+  },
+  endsAgentStep,
+})}
+`.trim()
+
+export const updateSubgoalParams = {
+  toolName,
+  endsAgentStep,
+  description,
+  inputSchema,
+  outputSchema: jsonToolResultSchema(
+    z.object({
+      message: z.string(),
+    }),
+  ),
+} satisfies $ToolParams