@alumbwe/anvil 1.0.20 → 1.0.22

package/vendor/@anvil/common/src/tools/params/tool/render-ui.ts

@@ -0,0 +1,168 @@
+import z from 'zod/v4'
+
+import { $getNativeToolCallExampleString, jsonToolResultSchema } from '../utils'
+
+import type { $ToolParams } from '../../constants'
+
+const toolName = 'render_ui'
+const endsAgentStep = false
+
+const buttonLinkSchema = z
+  .string()
+  .url()
+  .refine(
+    (value) => {
+      try {
+        const url = new URL(value)
+        return url.protocol === 'https:' || url.protocol === 'http:'
+      } catch {
+        return false
+      }
+    },
+    { message: 'Button links must use http:// or https://' },
+  )
+
+const gravityIndexButtonLinkSchema = z
+  .object({
+    source: z.literal('gravity_index'),
+    search_id: z
+      .string()
+      .min(1)
+      .describe('The exact search_id returned by gravity_index.'),
+    service_slug: z
+      .string()
+      .min(1)
+      .describe(
+        'The exact slug of the recommendation or option selected from that search.',
+      ),
+  })
+  .describe(
+    'A reference to a tracked click URL in a prior gravity_index search result. The runtime substitutes the exact stored URL.',
+  )
+
+export type RenderUIGravityIndexLink = z.infer<
+  typeof gravityIndexButtonLinkSchema
+>
+
+const buttonWidgetBaseSchema = z.object({
+  type: z
+    .literal('button')
+    .describe('Widget type. Currently, the only supported widget is button.'),
+  text: z
+    .string()
+    .min(1)
+    .max(80)
+    .describe('Short button label shown to the user.'),
+  variant: z
+    .enum(['primary', 'secondary'])
+    .optional()
+    .default('primary')
+    .describe(
+      'Theme-aware color treatment. Use primary for the main action and secondary for lower-emphasis actions.',
+    ),
+})
+
+const resolvedButtonWidgetSchema = buttonWidgetBaseSchema.extend({
+  link: buttonLinkSchema.describe(
+    'The http:// or https:// URL to open when the user clicks the button.',
+  ),
+})
+
+const buttonWidgetSchema = buttonWidgetBaseSchema.extend({
+  link: z
+    .union([buttonLinkSchema, gravityIndexButtonLinkSchema])
+    .describe(
+      'Either an http(s) URL or a gravity_index reference that the runtime resolves to the exact tracked click URL.',
+    ),
+})
+
+export type RenderUIButtonWidget = z.infer<typeof resolvedButtonWidgetSchema>
+
+/**
+ * Validates the resolved widget shape consumed by UI surfaces. Keeping this
+ * beside the tool schema gives CLI, Chat, Web, and Cloud one runtime contract.
+ */
+export function parseRenderUIButtonWidget(
+  widget: unknown,
+): RenderUIButtonWidget | null {
+  const rawLink =
+    widget && typeof widget === 'object' && !Array.isArray(widget)
+      ? (widget as { link?: unknown }).link
+      : undefined
+  if (typeof rawLink !== 'string') return null
+
+  const result = resolvedButtonWidgetSchema.safeParse(widget)
+  if (!result.success || result.data.link !== rawLink) return null
+
+  const text = result.data.text.trim()
+  return text ? { ...result.data, text } : null
+}
+
+const widgetSchema = z.discriminatedUnion('type', [buttonWidgetSchema])
+
+const inputSchema = z
+  .object({
+    widget: widgetSchema.describe('The UI widget to render.'),
+  })
+  .describe('Render a small interactive UI widget for the user.')
+
+const outputSchema = z.object({
+  message: z.string(),
+})
+
+const description = `
+Render a small interactive UI widget for the user.
+
+Currently supported widgets:
+- button: renders a clickable button with text and an http(s) link.
+
+Use this when the user should click a clear action, such as opening a generated report, documentation page, checkout page, deployment URL, preview, or dashboard.
+
+For a service selected from a gravity_index search, do not copy its opaque URL. Set \`link\` to a gravity_index reference containing the exact \`search_id\` and selected \`service_slug\`. The runtime verifies the selection against prior tool results and substitutes the exact stored click URL. Call render_ui only after deciding which service to recommend.
+
+Color variants:
+- primary: the main action
+- secondary: a lower-emphasis action
+
+Keep button text short and action-oriented.
+
+${$getNativeToolCallExampleString({
+  toolName,
+  inputSchema,
+  input: {
+    widget: {
+      type: 'button',
+      text: 'Open preview',
+      link: 'https://example.com/preview',
+      variant: 'primary',
+    },
+  },
+  endsAgentStep,
+})}
+
+${$getNativeToolCallExampleString({
+  toolName,
+  inputSchema,
+  input: {
+    widget: {
+      type: 'button',
+      text: 'Get your Resend API key',
+      link: {
+        source: 'gravity_index',
+        search_id: 'search_id_from_gravity_index',
+        service_slug: 'resend',
+      },
+      variant: 'primary',
+    },
+  },
+  endsAgentStep,
+})}
+`.trim()
+
+export const renderUIParams = {
+  toolName,
+  endsAgentStep,
+  description,
+  inputSchema,
+  outputSchema: jsonToolResultSchema(outputSchema),
+} satisfies $ToolParams

package/vendor/@anvil/common/src/tools/params/tool/run-file-change-hooks.ts

@@ -0,0 +1,57 @@
+import z from 'zod/v4'
+
+import { terminalCommandOutputSchema } from './run-terminal-command'
+import { $getNativeToolCallExampleString, jsonToolResultSchema } from '../utils'
+
+import type { $ToolParams } from '../../constants'
+
+const toolName = 'run_file_change_hooks'
+const endsAgentStep = true
+const inputSchema = z.object({
+  files: z
+    .array(z.string())
+    .describe(
+      `List of file paths that were changed and should trigger file change hooks`,
+    ),
+})
+const description = `
+Purpose: Trigger client-configured file change hooks for the specified files. This tool allows the backend to request the client to run its configured file change hooks (like tests, linting, type checking) after file changes have been applied.
+
+Use cases:
+- After making code changes, trigger the relevant tests and checks
+- Ensure code quality by running configured linters and type checkers
+- Validate that changes don't break the build
+
+The client will run only the hooks whose filePattern matches the provided files.
+
+Example:
+${$getNativeToolCallExampleString({
+  toolName,
+  inputSchema,
+  input: {
+    files: ['src/components/Button.tsx', 'src/utils/helpers.ts'],
+  },
+  endsAgentStep,
+})}
+`.trim()
+
+export const runFileChangeHooksParams = {
+  toolName,
+  endsAgentStep,
+  description,
+  inputSchema,
+  outputSchema: jsonToolResultSchema(
+    z
+      .union([
+        terminalCommandOutputSchema.and(
+          z.object({
+            hookName: z.string(),
+          }),
+        ),
+        z.object({
+          errorMessage: z.string(),
+        }),
+      ])
+      .array(),
+  ),
+} satisfies $ToolParams

package/vendor/@anvil/common/src/tools/params/tool/run-terminal-command.ts

@@ -0,0 +1,211 @@
+import z from 'zod/v4'
+
+import { $getNativeToolCallExampleString, jsonToolResultSchema } from '../utils'
+
+import type { $ToolParams } from '../../constants'
+
+/**
+ * Ceiling on a model-chosen SYNC command timeout.
+ *
+ * The value came straight from the model to the client with nothing in between
+ * — no clamp anywhere in the runtime — and the only guidance was "Default 30".
+ * In practice models picked 3-minute, 10-minute and 50-minute budgets for work
+ * that finishes in seconds, and the cost of an over-long value is paid entirely
+ * by the user: when the command does hang, they wait the whole budget watching
+ * nothing happen.
+ *
+ * 10 minutes is above any legitimate SYNC command we ship (the longest bundled
+ * agent budget is the librarian's 180s `git clone`) while cutting the tail that
+ * makes a hang indistinguishable from a freeze. Genuinely open-ended work has
+ * two better doors that this does not touch: `-1` for an explicit indefinite
+ * wait, and `process_type: BACKGROUND` for long-running processes.
+ */
+export const MAX_TERMINAL_TIMEOUT_SECONDS = 600
+export const MAX_TERMINAL_TIMEOUT_MINUTES = MAX_TERMINAL_TIMEOUT_SECONDS / 60
+
+/** Clamp a model-supplied timeout, preserving the -1 "no timeout" sentinel and
+ *  leaving an absent value to the schema default. */
+export function clampTerminalTimeoutSeconds(
+  seconds: number | undefined,
+): number | undefined {
+  if (seconds === undefined) return undefined
+  if (seconds === -1) return -1
+  if (!Number.isFinite(seconds)) return MAX_TERMINAL_TIMEOUT_SECONDS
+  // A zero or negative value other than -1 is nonsense rather than a request
+  // for a short wait; fall back to the default instead of failing instantly.
+  if (seconds <= 0) return 30
+  return Math.min(seconds, MAX_TERMINAL_TIMEOUT_SECONDS)
+}
+
+export const terminalCommandOutputSchema = z.union([
+  z.object({
+    command: z.string(),
+    startingCwd: z.string().optional(),
+    message: z.string().optional(),
+    stderr: z.string().optional(),
+    stdout: z.string().optional(),
+    exitCode: z.number().optional(),
+  }),
+  z.object({
+    command: z.string(),
+    startingCwd: z.string().optional(),
+    message: z.string().optional(),
+    stderr: z.string().optional(),
+    stdoutOmittedForLength: z.literal(true),
+    exitCode: z.number().optional(),
+  }),
+  z.object({
+    command: z.string(),
+    processId: z.number(),
+    backgroundProcessStatus: z.enum(['running', 'completed', 'error']),
+  }),
+  z.object({
+    command: z.string(),
+    errorMessage: z.string(),
+  }),
+])
+
+export const gitCommitGuidePrompt = `
+### Using git to commit changes
+
+When the user requests a new git commit, please follow these steps closely:
+
+1. **Run two run_terminal_command tool calls:**
+   - Run \`git diff\` to review both staged and unstaged modifications.
+   - Run \`git log\` to check recent commit messages, ensuring consistency with this repository's style.
+
+2. **Select relevant files to include in the commit:**
+   Use the git context established at the start of this conversation to decide which files are pertinent to the changes. Stage any new untracked files that are relevant, but avoid committing previously modified files (from the beginning of the conversation) unless they directly relate to this commit.
+
+3. **Analyze the staged changes and compose a commit message:**
+   Enclose your analysis in <commit_analysis> tags. Within these tags, you should:
+   - Note which files have been altered or added.
+   - Categorize the nature of the changes (e.g., new feature, fix, refactor, documentation, etc.).
+   - Consider the purpose or motivation behind the alterations.
+   - Refrain from using tools to inspect code beyond what is presented in the git context.
+   - Evaluate the overall impact on the project.
+   - Check for sensitive details that should not be committed.
+   - Draft a concise, one- to two-sentence commit message focusing on the “why” rather than the “what.”
+   - Use precise, straightforward language that accurately represents the changes.
+   - Ensure the message provides clarity—avoid generic or vague terms like “Update” or “Fix” without context.
+   - Revisit your draft to confirm it truly reflects the changes and their intention.
+
+4. **Create the commit, ending with this specific footer:**
+   \`\`\`
+   Generated with Anvil 🤖
+   Co-Authored-By: Anvil <noreply@codebuff.com>
+   \`\`\`
+   Commands run in bash on every OS (Git Bash on Windows), so always use HEREDOC syntax to format the message:
+   \`\`\`
+   git commit -m "$(cat <<'EOF'
+   Your commit message here.
+
+   🤖 Generated with Anvil
+   Co-Authored-By: Anvil <noreply@codebuff.com>
+   EOF
+   )"
+   \`\`\`
+
+**Important details**
+
+- When feasible, use a single \`git commit -am\` command to add and commit together, but do not accidentally stage unrelated files.
+- Never alter the git config.
+- Do not push to the remote repository.
+- Avoid using interactive flags (e.g., \`-i\`) that require unsupported interactive input.
+- Do not create an empty commit if there are no changes.
+- Make sure your commit message is concise yet descriptive, focusing on the intention behind the changes rather than merely describing them.
+`
+
+const toolName = 'run_terminal_command'
+const endsAgentStep = true
+const inputSchema = z
+  .object({
+    // Can be empty to use it for a timeout.
+    command: z
+      .string()
+      .min(1, 'Command cannot be empty')
+      .describe(
+        `CLI command. Always executed with bash (Git Bash on Windows), so use POSIX syntax on every OS: \`mv\`/\`rm\`, \`/dev/null\`, heredocs. Never use cmd.exe syntax like \`del\`, \`move\`, or \`> nul\` — on Windows \`> nul\` creates a literal file named "nul" that is very hard to delete.`,
+      ),
+    process_type: z
+      .enum(['SYNC', 'BACKGROUND'])
+      .default('SYNC')
+      .describe(
+        `Either SYNC (waits, returns output) or BACKGROUND (runs in background). Default SYNC`,
+      ),
+    cwd: z
+      .string()
+      .optional()
+      .describe(
+        `The working directory to run the command in. Default is the project root.`,
+      ),
+    timeout_seconds: z
+      .number()
+      .default(30)
+      .optional()
+      .transform(clampTerminalTimeoutSeconds)
+      .describe(
+        `How long to wait, in seconds. Default 30, which is right for almost everything — omit this field unless the command genuinely runs longer. Budget for the command you are actually running (a typecheck or test run is tens of seconds, not minutes); an over-long value does not make a command safer, it just means you wait that long when something hangs. Values above ${MAX_TERMINAL_TIMEOUT_SECONDS} (${MAX_TERMINAL_TIMEOUT_MINUTES} minutes) are clamped. Set to -1 to wait indefinitely, for genuinely open-ended commands only. Does not apply for BACKGROUND commands — use those for long-running processes instead.`,
+      ),
+  })
+  .describe(
+    `Execute a CLI command from the **project root** (different from the user's cwd).`,
+  )
+const description = `
+Stick to these use cases:
+1. Typechecking the project or running build (e.g., "npm run build"). Reading the output can help you edit code to fix build errors. If possible, use an option that performs checks but doesn't emit files, e.g. \`tsc --noEmit\`.
+2. Running tests (e.g., "npm test"). Reading the output can help you edit code to fix failing tests. Or, you could write new unit tests and then run them.
+3. Moving, renaming, or deleting files and directories. These actions can be vital for refactoring requests. Use \`mv\` or \`rm\` (commands run in bash on every OS, including Windows — do not use \`move\`/\`del\`).
+
+Most likely, you should ask for permission for any other type of command you want to run. If asking for permission, show the user the command you want to run using \`\`\` tags and *do not* use the tool call format, e.g.:
+\`\`\`bash
+git branch -D foo
+\`\`\`
+
+DO NOT do any of the following:
+1. Run commands that can modify files outside of the project directory, install packages globally, install virtual environments, or have significant side effects outside of the project directory, unless you have explicit permission from the user. Treat anything outside of the project directory as read-only.
+2. Run \`git push\` because it can break production (!) if the user was not expecting it. Don't run \`git commit\`, \`git rebase\`, or related commands unless you get explicit permission. If a user asks to commit changes, you can do so, but you should not invoke any further git commands beyond the git commit command.
+3. Run scripts without asking. Especially don't run scripts that could run against the production environment or have permanent effects without explicit permission from the user.
+4. Be careful with any command that has big or irreversible effects. Anything that touches a production environment, servers, the database, or other systems that could be affected by a command should be run with explicit permission from the user.
+5. Use the run_terminal_command tool to create or edit files. Do not use \`cat\` or \`echo\` to create or edit files. You should instead use other tools for creating or editing files.
+6. Use the wrong package manager for the project. For example, if the project uses \`pnpm\` or \`bun\` or \`yarn\`, you should not use \`npm\`. Similarly not everyone uses \`pip\` for python, etc.
+
+Do:
+- If there's an opportunity to use "-y" or "--yes" flags, use them. Any command that prompts for confirmation will hang if you don't use the flags.
+
+Notes:
+- If the user references a specific file, it could be either from their cwd or from the project root. You **must** determine which they are referring to (either infer or ask). Then, you must specify the path relative to the project root (or use the cwd parameter)
+- Commands can succeed without giving any output, e.g. if no type errors were found.
+
+${gitCommitGuidePrompt}
+
+Example:
+${$getNativeToolCallExampleString({
+  toolName,
+  inputSchema,
+  input: {
+    command: 'echo "hello world"',
+  },
+  endsAgentStep,
+})}
+
+${$getNativeToolCallExampleString({
+  toolName,
+  inputSchema,
+  input: {
+    command: `git commit -m "Your commit message here.
+
+🤖 Generated with Anvil
+Co-Authored-By: Anvil <noreply@codebuff.com>"`,
+  },
+  endsAgentStep,
+})}
+    `.trim()
+
+export const runTerminalCommandParams = {
+  toolName,
+  endsAgentStep,
+  description,
+  inputSchema,
+  outputSchema: jsonToolResultSchema(terminalCommandOutputSchema),
+} satisfies $ToolParams

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

@@ -0,0 +1,97 @@
+import z from 'zod/v4'
+
+import { jsonToolResultSchema } from '../utils'
+
+import type { $ToolParams } from '../../constants'
+
+const toolName = 'screenshot'
+const endsAgentStep = true
+
+const inputSchema = z
+  .object({
+    url: z
+      .string()
+      .describe(
+        'The URL to capture. Can be a local dev server (http://localhost:3000) or any public URL.',
+      ),
+    output_path: z
+      .string()
+      .optional()
+      .describe(
+        'File path to save the screenshot. Defaults to ./screenshot.png relative to the project root.',
+      ),
+    width: z
+      .number()
+      .optional()
+      .default(1280)
+      .describe('Viewport width in pixels. Default 1280.'),
+    height: z
+      .number()
+      .optional()
+      .default(800)
+      .describe('Viewport height in pixels. Default 800.'),
+    full_page: z
+      .boolean()
+      .optional()
+      .default(false)
+      .describe(
+        'If true, capture the full scrollable page. If false, capture only the viewport.',
+      ),
+    wait_ms: z
+      .number()
+      .optional()
+      .default(2000)
+      .describe(
+        'Milliseconds to wait after page load before capturing. Allows animations and lazy content to render. Default 2000.',
+      ),
+    dark_mode: z
+      .boolean()
+      .optional()
+      .default(false)
+      .describe(
+        'If true, emulate dark mode (prefers-color-scheme: dark) before capturing.',
+      ),
+  })
+  .describe(
+    'Capture a screenshot of a web page using Chrome headless. Requires Chrome to be installed.',
+  )
+
+const screenshotOutputSchema = z.object({
+  success: z.boolean(),
+  output_path: z.string().optional(),
+  message: z.string(),
+  width: z.number(),
+  height: z.number(),
+})
+
+const description = `
+Capture a screenshot of a web page using Chrome's headless mode.
+
+**Use cases:**
+- After building a UI, screenshot it to verify the visual result
+- Capture before/after states for comparison
+- Feed screenshots to vision_analyze for AI-powered design critique
+
+**How it works:**
+1. Launches Chrome in headless mode with the specified viewport
+2. Navigates to the URL and waits for content to render
+3. Captures the screenshot (viewport or full page)
+4. Saves to the specified output path
+
+**Requirements:**
+- Chrome must be installed on the system
+- The URL must be accessible (local dev server or public URL)
+
+**Examples:**
+- Screenshot a local dev server: url="http://localhost:3000"
+- Screenshot with dark mode: url="http://localhost:3000", dark_mode=true
+- Full page screenshot: url="http://localhost:3000", full_page=true
+`.trim()
+
+export const screenshotParams = {
+  toolName,
+  endsAgentStep,
+  description,
+  inputSchema,
+  outputSchema: jsonToolResultSchema(screenshotOutputSchema),
+} satisfies $ToolParams

package/vendor/@anvil/common/src/tools/params/tool/set-messages.ts

@@ -0,0 +1,44 @@
+import z from 'zod/v4'
+
+import {
+  $getNativeToolCallExampleString,
+  textToolResultSchema,
+} from '../utils'
+
+import type { $ToolParams } from '../../constants'
+
+const toolName = 'set_messages'
+const endsAgentStep = true
+const inputSchema = z
+  .object({
+    messages: z.any(),
+  })
+  .describe(`Set the conversation history to the provided messages.`)
+const description = `
+Example:
+${$getNativeToolCallExampleString({
+  toolName,
+  inputSchema,
+  input: {
+    messages: [
+      {
+        role: 'user',
+        content: 'Hello, how are you?',
+      },
+      {
+        role: 'assistant',
+        content: 'I am fine, thank you.',
+      },
+    ],
+  },
+  endsAgentStep,
+})}
+`.trim()
+
+export const setMessagesParams = {
+  toolName,
+  endsAgentStep,
+  description,
+  inputSchema,
+  outputSchema: textToolResultSchema(),
+} satisfies $ToolParams

package/vendor/@anvil/common/src/tools/params/tool/set-output.ts

@@ -0,0 +1,61 @@
+import z from 'zod/v4'
+
+import { $getNativeToolCallExampleString } from '../utils'
+
+import type { $ToolParams } from '../../constants'
+
+const toolName = 'set_output'
+const endsAgentStep = false
+
+// WHY `data` EXISTS IN THE INPUT SCHEMA:
+// Subagents inherit their parent's tool definitions, and because of prompt caching
+// we cannot modify or add tools mid-conversation. OpenAI models enforce the tool's
+// input schema strictly, so we need a permissive shape that any model can call.
+// An empty schema or `z.object({}).passthrough()` would be rejected by OpenAI's
+// strict schema enforcement. The `data: z.record(...)` field is a deliberately
+// vague shape that satisfies OpenAI while allowing us to inject the real
+// outputSchema later in the conversation (in the instructions prompt).
+//
+// At runtime, the handler (`packages/agent-runtime/src/tools/handlers/tool/set-output.ts`)
+// tries parsing against the real outputSchema in two ways:
+//   1. Parse the raw output (agent passed fields at top level)
+//   2. Fallback: parse `output.data` (agent wrapped fields in `data`)
+// This means both `{ results: [...] }` and `{ data: { results: [...] } }` are accepted.
+const inputSchema = z
+  .looseObject({
+    data: z.record(z.string(), z.any()).optional(),
+  })
+  .describe(
+    'JSON object to set as the agent output. The shape of the parameters are specified dynamically further down in the conversation. This completely replaces any previous output. If the agent was spawned, this value will be passed back to its parent. If the agent has an outputSchema defined, the output will be validated against it.',
+  )
+const description = `
+Subagents must use this tool as it is the only way to report any findings. Nothing else you write will be visible to the user/parent agent.
+
+Note that the output schema is provided dynamically in a user prompt further down in the conversation. Be sure to follow what the latest output schema is when using this tool.
+
+Please set the output with all the information and analysis you want to pass on. If you just want to send a simple message, use an object with the key "message" and value of the message you want to send.
+Example:
+${$getNativeToolCallExampleString({
+  toolName,
+  inputSchema,
+  input: {
+    message: 'I found a bug in the code!',
+  },
+  endsAgentStep,
+})}
+`.trim()
+
+export const setOutputParams = {
+  toolName,
+  endsAgentStep,
+  description,
+  inputSchema,
+  outputSchema: z.tuple([
+    z.object({
+      type: z.literal('json'),
+      value: z.object({
+        message: z.string(),
+      }),
+    }),
+  ]),
+} satisfies $ToolParams