@alumbwe/anvil 1.0.20 → 1.0.22

package/vendor/@anvil/common/src/tools/params/tool/vision-analyze.ts

@@ -0,0 +1,82 @@
+import z from 'zod/v4'
+
+import { jsonToolResultSchema } from '../utils'
+
+import type { $ToolParams } from '../../constants'
+
+const toolName = 'vision_analyze'
+const endsAgentStep = true
+
+const inputSchema = z
+  .object({
+    image_path: z
+      .string()
+      .describe(
+        'Path to the image file to analyze. Can be a screenshot captured with the screenshot tool, or any image file.',
+      ),
+    prompt: z
+      .string()
+      .describe(
+        'What to analyze about the image. Examples: "Critique this UI design", "Check if dark mode is properly implemented", "Compare spacing and alignment", "Evaluate typography hierarchy".',
+      ),
+    context: z
+      .string()
+      .optional()
+      .describe(
+        'Optional context about what the image shows (e.g. "This is a SaaS landing page hero section"). Helps the vision model give more targeted feedback.',
+      ),
+    focus_areas: z
+      .array(z.string())
+      .optional()
+      .describe(
+        'Specific areas to focus on. Examples: ["color contrast", "button styling", "spacing", "typography", "layout", "dark mode"].',
+      ),
+  })
+  .describe(
+    'Analyze a UI screenshot using Gemini vision. Get AI-powered design critique, accessibility feedback, and improvement suggestions.',
+  )
+
+const visionAnalyzeOutputSchema = z.object({
+  analysis: z.string(),
+  issues_found: z.array(
+    z.object({
+      severity: z.enum(['critical', 'warning', 'info']),
+      area: z.string(),
+      description: z.string(),
+      suggestion: z.string(),
+    }),
+  ),
+  score: z.number().min(0).max(10),
+  summary: z.string(),
+})
+
+const description = `
+Analyze a UI screenshot using Gemini's vision capabilities for AI-powered design critique.
+
+**Use cases:**
+- Get design feedback after building a UI
+- Check accessibility (contrast, spacing, readability)
+- Compare against design system rules
+- Validate dark mode implementation
+- Get suggestions for visual improvements
+
+**How it works:**
+1. Reads the image file (supports PNG, JPG, WebP)
+2. Sends it to Gemini's vision API with your analysis prompt
+3. Returns structured feedback with issues, severity, and suggestions
+
+**Requires:** GEMINI_API_KEY environment variable or .env.local entry.
+
+**Examples:**
+- Critique a landing page: image_path="./screenshot.png", prompt="Critique this landing page hero section"
+- Check dark mode: image_path="./dark-mode.png", prompt="Is dark mode properly implemented?", focus_areas=["contrast", "colors"]
+- Accessibility check: image_path="./ui.png", prompt="Check this UI for accessibility issues", focus_areas=["color contrast", "text sizing", "touch targets"]
+`.trim()
+
+export const visionAnalyzeParams = {
+  toolName,
+  endsAgentStep,
+  description,
+  inputSchema,
+  outputSchema: jsonToolResultSchema(visionAnalyzeOutputSchema),
+} satisfies $ToolParams

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

@@ -0,0 +1,73 @@
+import z from 'zod/v4'
+
+import { $getNativeToolCallExampleString, jsonToolResultSchema } from '../utils'
+
+import type { $ToolParams } from '../../constants'
+
+const toolName = 'web_search'
+const endsAgentStep = true
+const inputSchema = z
+  .object({
+    query: z
+      .string()
+      .min(1, 'Query cannot be empty')
+      .describe(`The search query to find relevant web content`),
+    depth: z
+      .enum(['standard', 'deep'])
+      .optional()
+      .default('standard')
+      .describe(
+        `Search depth - 'standard' for quick results, 'deep' for more comprehensive search. Default is 'standard'.`,
+      ),
+  })
+  .describe(`Search the web for current information using Serper API.`)
+const description = `
+Purpose: Search the web for current, up-to-date information on any topic. This tool uses Serper's Google Search API to find relevant content from across the internet.
+
+Use cases:
+- Finding current information about technologies, libraries, or frameworks
+- Researching best practices and solutions
+- Getting up-to-date news or documentation
+- Finding examples and tutorials
+- Checking current status of services or APIs
+
+The tool will return JSON search results with titles, URLs, content snippets, and other available SERP fields such as answer boxes or related questions.
+
+Example:
+${$getNativeToolCallExampleString({
+  toolName,
+  inputSchema,
+  input: {
+    query: 'Next.js 15 new features',
+    depth: 'standard',
+  },
+  endsAgentStep,
+})}
+
+${$getNativeToolCallExampleString({
+  toolName,
+  inputSchema,
+  input: {
+    query: 'React Server Components tutorial',
+    depth: 'deep',
+  },
+  endsAgentStep,
+})}
+`.trim()
+
+export const webSearchParams = {
+  toolName,
+  endsAgentStep,
+  description,
+  inputSchema,
+  outputSchema: jsonToolResultSchema(
+    z.union([
+      z.object({
+        result: z.string(),
+      }),
+      z.object({
+        errorMessage: z.string(),
+      }),
+    ]),
+  ),
+} satisfies $ToolParams

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

@@ -0,0 +1,71 @@
+import z from 'zod/v4'
+
+import { updateFileResultSchema } from './str-replace'
+import { $getNativeToolCallExampleString, jsonToolResultSchema } from '../utils'
+
+import type { $ToolParams } from '../../constants'
+
+const toolName = '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(`Create or overwrite a file with the given content.`)
+const description = `
+Create or replace a file with the given content.
+
+Format the \`content\` parameter with the entire content of the file.
+
+#### Additional Info
+
+Do not use this tool to delete or rename a file. Instead run a terminal command for that.
+
+Examples:
+
+Example 1 - Simple file creation:
+${$getNativeToolCallExampleString({
+  toolName,
+  inputSchema,
+  input: {
+    path: 'new-file.ts',
+    instructions: 'Prints Hello, world',
+    content: 'console.log("Hello, world!");',
+  },
+  endsAgentStep,
+})}
+
+Example 2 - 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 writeFileParams = {
+  toolName,
+  endsAgentStep,
+  description,
+  inputSchema,
+  outputSchema: jsonToolResultSchema(updateFileResultSchema),
+} satisfies $ToolParams

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

@@ -0,0 +1,67 @@
+import z from 'zod/v4'
+
+import { $getNativeToolCallExampleString, coerceToArray } from '../utils'
+
+import type { $ToolParams } from '../../constants'
+
+const toolName = 'write_todos'
+const endsAgentStep = false
+const inputSchema = z
+  .object({
+    todos: z
+      .preprocess(
+        coerceToArray,
+        z.array(
+          z.object({
+            task: z.string().describe('Description of the task'),
+            completed: z.boolean().describe('Whether the task is completed'),
+          }),
+        ),
+      )
+      .describe(
+        "List of todos with their completion status. Add ALL of the applicable tasks to the list, so you don't forget to do anything. Try to order the todos the same way you will complete them. Do not mark todos as completed if you have not completed them yet!",
+      ),
+  })
+  .describe(
+    'Write a todo list to track tasks for multi-step implementations. Use this frequently to maintain an updated step-by-step plan.',
+  )
+const description = `
+Use this tool to track your objectives through an ordered step-by-step plan. Call this tool after you have gathered context on the user's request to plan out the implementation steps for the user's request.
+
+After completing each todo step, call this tool again to update the list and mark that task as completed. Note that each time you call this tool, rewrite ALL todos with their current status.
+
+Use this tool frequently as you work through tasks to update the list of todos with their current status. Doing this is extremely useful because it helps you stay on track and complete all the requirements of the user's request. It also helps inform the user of your plans and the current progress, which they want to know at all times.
+
+Example:
+${$getNativeToolCallExampleString({
+  toolName,
+  inputSchema,
+  input: {
+    todos: [
+      { task: 'Create new implementation in foo.ts', completed: true },
+      { task: 'Update bar.ts to use the new implementation', completed: false },
+      { task: 'Write tests for the new implementation', completed: false },
+      {
+        task: 'Run the tests to verify the new implementation',
+        completed: false,
+      },
+    ],
+  },
+  endsAgentStep,
+})}
+`.trim()
+
+export const writeTodosParams = {
+  toolName,
+  endsAgentStep,
+  description,
+  inputSchema,
+  outputSchema: z.tuple([
+    z.object({
+      type: z.literal('json'),
+      value: z.object({
+        message: z.string(),
+      }),
+    }),
+  ]),
+} satisfies $ToolParams

package/vendor/@anvil/common/src/tools/params/utils.ts

@@ -0,0 +1,150 @@
+import z from 'zod/v4'
+
+import {
+  endsAgentStepParam,
+  endToolTag,
+  startToolTag,
+  toolNameParam,
+} from '../constants'
+
+import type { JSONValue } from '../../types/json'
+import type { ToolResultOutput } from '../../types/messages/content-part'
+
+/**
+ * Coerces a value into an array if it isn't one already.
+ * Handles common LLM mistakes:
+ * - Single object/string passed instead of an array → wraps in array
+ * - Stringified JSON array passed as a string → parses it
+ * - Already an array → passes through
+ * - null/undefined → passes through (let Zod handle it)
+ */
+export function coerceToArray(val: unknown): unknown {
+  if (Array.isArray(val)) return val
+  if (typeof val === 'string') {
+    try {
+      const parsed = JSON.parse(val)
+      if (Array.isArray(parsed)) return parsed
+    } catch {
+      // Not valid JSON — fall through to wrap
+    }
+  }
+  if (val != null) return [val]
+  return val
+}
+
+/**
+ * Coerces a stringified JSON object into an object.
+ * This is intentionally narrow so malformed values still fail validation.
+ */
+export function coerceToObject(val: unknown): unknown {
+  if (typeof val !== 'string') {
+    return val
+  }
+
+  try {
+    const parsed = JSON.parse(val)
+    if (
+      parsed != null &&
+      typeof parsed === 'object' &&
+      !Array.isArray(parsed)
+    ) {
+      return parsed
+    }
+  } catch {
+    // Leave the original value untouched so schema validation can reject it.
+  }
+
+  return val
+}
+
+/**
+ * Handles common replacement-key aliases emitted by some models while keeping
+ * the documented schema stable.
+ */
+export function normalizeReplacementAliases(val: unknown): unknown {
+  if (val === null || typeof val !== 'object' || Array.isArray(val)) {
+    return val
+  }
+
+  const replacement = { ...(val as Record<string, unknown>) }
+  for (const [target, aliases] of [
+    ['oldString', ['old', 'old_str', 'old_string']],
+    ['newString', ['new', 'new_str', 'new_string']],
+  ] as const) {
+    if (replacement[target] !== undefined) {
+      continue
+    }
+    const alias = aliases.find((key) => typeof replacement[key] === 'string')
+    if (alias) {
+      replacement[target] = replacement[alias]
+    }
+  }
+  return replacement
+}
+
+/** Only used for generating tool call strings before all tools are defined.
+ *
+ * @param toolName - The name of the tool to call
+ * @param inputSchema - The zod schema for the tool. This is only used as type validation and is unused otherwise.
+ * @param input - The input to the tool
+ * @param endsAgentStep - Whether the agent should end its turn after this tool call
+ */
+export function $getToolCallString<Input>(params: {
+  toolName: string
+  inputSchema: z.ZodType<any, Input> | null
+  input: Input
+  endsAgentStep: boolean
+}): string {
+  const { toolName, input, endsAgentStep } = params
+  const obj: Record<string, any> = {
+    [toolNameParam]: toolName,
+    ...input,
+  }
+  if (endsAgentStep) {
+    obj[endsAgentStepParam] = endsAgentStep satisfies true
+  }
+  return [startToolTag, JSON.stringify(obj, null, 2), endToolTag].join('')
+}
+
+export function $getNativeToolCallExampleString<Input>(params: {
+  toolName: string
+  inputSchema: z.ZodType<any, Input> | null
+  input: Input
+  endsAgentStep?: boolean // unused
+}): string {
+  const { toolName, input } = params
+  return [
+    `<${toolName}_params_example>\n`,
+    JSON.stringify(input, null, 2),
+    `\n</${toolName}_params_example>`,
+  ].join('')
+}
+
+/** Generates the zod schema for a single JSON tool result. */
+export function jsonToolResultSchema<T extends JSONValue>(
+  valueSchema: z.ZodType<T>,
+) {
+  return z.tuple([
+    z.object({
+      type: z.literal('json'),
+      value: valueSchema,
+    }) satisfies z.ZodType<ToolResultOutput>,
+  ])
+}
+
+/** Generates the zod schema for an empty tool result. */
+export function emptyToolResultSchema() {
+  return z.tuple([])
+}
+
+/** Generates the zod schema for a simple text tool result. */
+export function textToolResultSchema() {
+  return z.tuple([
+    z.object({
+      type: z.literal('json'),
+      value: z.object({
+        message: z.string(),
+      }),
+    }) satisfies z.ZodType<ToolResultOutput>,
+  ])
+}

package/vendor/@anvil/common/src/tools/utils.ts

@@ -0,0 +1,24 @@
+import { toolParams } from './list'
+import { $getToolCallString } from './params/utils'
+
+import type { ToolName } from './constants'
+import type z from 'zod/v4'
+
+export function getToolCallString<T extends ToolName | (string & {})>(
+  toolName: T,
+  input: T extends ToolName
+    ? z.input<(typeof toolParams)[T]['inputSchema']>
+    : Record<string, any>,
+  ...endsAgentStep: T extends ToolName ? [] : [boolean]
+): string {
+  const endsAgentStepValue =
+    toolName in toolParams
+      ? toolParams[toolName as keyof typeof toolParams].endsAgentStep
+      : endsAgentStep[0] ?? false
+  return $getToolCallString({
+    toolName,
+    inputSchema: null,
+    input,
+    endsAgentStep: endsAgentStepValue,
+  })
+}

package/vendor/@anvil/common/src/types/__tests__/dynamic-agent-template.test.ts

@@ -0,0 +1,20 @@
+import type { AgentDefinition } from '../../templates/initial-agents-dir/types/agent-definition'
+import type { publishedTools } from '../../tools/constants'
+import type { DynamicAgentDefinition } from '../dynamic-agent-template'
+
+// Create a version of DynamicAgentDefinition where handleSteps is compatible with AgentDefinition
+
+type DynamicAgentDefinitionHandleSteps = Omit<
+  DynamicAgentDefinition,
+  'handleSteps' | 'toolNames'
+> & {
+  handleSteps?: AgentDefinition['handleSteps']
+  toolNames?: (typeof publishedTools | (string & {}))[number][]
+}
+// Don't remove these lines! And don't change the values away from true!
+const _typecheck1: DynamicAgentDefinitionHandleSteps = {} as AgentDefinition
+const _typecheck2: AgentDefinition = {} as DynamicAgentDefinitionHandleSteps
+const _keyTypecheck1: keyof AgentDefinition =
+  {} as keyof DynamicAgentDefinitionHandleSteps
+const _keyTypecheck2: keyof DynamicAgentDefinitionHandleSteps =
+  {} as keyof AgentDefinition

package/vendor/@anvil/common/src/types/agent-template.ts

@@ -0,0 +1,215 @@
+/**
+ * Backend Agent Template Types
+ *
+ * This file provides backend-compatible agent template types with strict validation.
+ * It imports base types from the user-facing template to eliminate duplication.
+ */
+
+import { z } from 'zod/v4'
+
+import type { MCPConfig } from './mcp'
+import type { Model } from '../old-constants'
+import type { ToolResultOutput } from './messages/content-part'
+import type { AgentState, AgentTemplateType } from './session-state'
+import type {
+  ToolCall,
+  AgentState as PublicAgentState,
+} from '../templates/initial-agents-dir/types/agent-definition'
+import type { Logger } from '../templates/initial-agents-dir/types/util-types'
+import type { ToolName } from '../tools/constants'
+
+export type AgentId = `${string}/${string}@${number}.${number}.${number}`
+
+export type OpenRouterReasoningOptions = {
+  /**
+   * https://openrouter.ai/docs/use-cases/reasoning-tokens
+   * One of `max_tokens` or `effort` is required.
+   * If `exclude` is true, reasoning will be removed from the response. Default is false.
+   */
+  enabled?: boolean
+  exclude?: boolean
+} & (
+  | {
+      max_tokens: number
+    }
+  | {
+      effort: 'high' | 'medium' | 'low' | 'minimal' | 'none'
+    }
+)
+
+export type OpenRouterProviderRoutingOptions = {
+  /**
+   * List of provider slugs to try in order (e.g. ["anthropic", "openai"])
+   */
+  order?: string[]
+  /**
+   * Whether to allow backup providers when primary is unavailable (default: true)
+   */
+  allow_fallbacks?: boolean
+  /**
+   * Only use providers that support all parameters in your request (default: false)
+   */
+  require_parameters?: boolean
+  /**
+   * Control whether to use providers that may store data
+   */
+  data_collection?: 'allow' | 'deny'
+  /**
+   * List of provider slugs to allow for this request
+   */
+  only?: string[]
+  /**
+   * List of provider slugs to skip for this request
+   */
+  ignore?: string[]
+  /**
+   * List of quantization levels to filter by (e.g. ["int4", "int8"])
+   */
+  quantizations?: Array<
+    | 'int4'
+    | 'int8'
+    | 'fp4'
+    | 'fp6'
+    | 'fp8'
+    | 'fp16'
+    | 'bf16'
+    | 'fp32'
+    | 'unknown'
+  >
+  /**
+   * Sort providers by price, throughput, or latency
+   */
+  sort?: 'price' | 'throughput' | 'latency'
+  /**
+   * Maximum pricing you want to pay for this request
+   */
+  max_price?: {
+    prompt?: number | string
+    completion?: number | string
+    image?: number | string
+    audio?: number | string
+    request?: number | string
+  }
+}
+
+export type OpenRouterProviderOptions = {
+  models?: string[]
+  reasoning?: OpenRouterReasoningOptions
+  /**
+   * A unique identifier representing your end-user, which can
+   * help OpenRouter to monitor and detect abuse.
+   */
+  user?: string
+}
+
+/**
+ * Backend agent template with strict validation and Zod schemas
+ * Extends the user-facing AgentDefinition but with backend-specific requirements
+ */
+export type AgentTemplate<
+  P = string | undefined,
+  T = Record<string, any> | undefined,
+> = {
+  id: AgentTemplateType
+  displayName: string
+  model: Model
+  reasoningOptions?: OpenRouterReasoningOptions
+  providerOptions?: OpenRouterProviderRoutingOptions
+
+  mcpServers: Record<string, MCPConfig>
+  toolNames: (ToolName | (string & {}))[]
+  spawnableAgents: AgentTemplateType[]
+
+  spawnerPrompt?: string
+  systemPrompt: string
+  instructionsPrompt: string
+  stepPrompt: string
+  parentInstructions?: Record<string, string>
+
+  // Required parameters for spawning this agent.
+  inputSchema: {
+    prompt?: z.ZodSchema<P>
+    params?: z.ZodSchema<T>
+  }
+  includeMessageHistory: boolean
+  inheritParentSystemPrompt: boolean
+  windowedFileReads?: boolean
+  compactContext?:
+    | boolean
+    | { cacheExpiryMs?: number | null; cacheExpiryMinTokens?: number | null }
+  outputMode: 'last_message' | 'all_messages' | 'structured_output'
+  outputSchema?: z.ZodSchema<any>
+
+  handleSteps?: StepHandler<P, T> | string // Function or string of the generator code for running in a sandbox
+  /**
+   * Live copy of handleSteps kept alongside the serialized string. The string
+   * form of a bundled function can reference out-of-scope bundler helpers
+   * (esbuild keepNames injects `__name(...)`, minified to a bare identifier),
+   * which breaks the eval path. When the runtime is in-process, prefer this
+   * function. Dropped automatically by JSON serialization (resume blobs, DB).
+   */
+  handleStepsFn?: StepHandler<P, T>
+}
+
+export type StepText = { type: 'STEP_TEXT'; text: string }
+export type GenerateN = { type: 'GENERATE_N'; n: number }
+
+// Zod schemas for handleSteps yield values
+export const StepTextSchema = z.object({
+  type: z.literal('STEP_TEXT'),
+  text: z.string(),
+})
+
+export const GenerateNSchema = z.object({
+  type: z.literal('GENERATE_N'),
+  n: z.number().int().positive(),
+})
+
+export const HandleStepsToolCallSchema = z.object({
+  toolName: z.string().min(1),
+  input: z.record(z.string(), z.any()),
+  includeToolCall: z.boolean().optional(),
+})
+
+export const HandleStepsYieldValueSchema = z.union([
+  z.literal('STEP'),
+  z.literal('STEP_ALL'),
+  StepTextSchema,
+  GenerateNSchema,
+  HandleStepsToolCallSchema,
+])
+
+export type HandleStepsYieldValue = z.infer<typeof HandleStepsYieldValueSchema>
+
+export type StepGenerator = Generator<
+  Omit<ToolCall, 'toolCallId'> | 'STEP' | 'STEP_ALL' | StepText | GenerateN, // Generic tool call type
+  void,
+  {
+    agentState: PublicAgentState
+    toolResult: ToolResultOutput[]
+    stepsComplete: boolean
+    nResponses?: string[]
+  }
+>
+
+export type StepHandler<
+  P = string | undefined,
+  T = Record<string, any> | undefined,
+> = (context: {
+  agentState: AgentState
+  prompt: P
+  params: T
+  /**
+   * The model this agent step is running on, after any per-request override of
+   * the template's `model`. Needed because `handleSteps` is serialized with
+   * `toString()` (no closures survive), so a caller that swaps the model at
+   * request time has no other way to tell the generator which model it got.
+   *
+   * Supplied by the runtime; optional so generators invoked directly in tests
+   * keep compiling. Treat `undefined` as "unknown model".
+   */
+  model?: string
+  logger: Logger
+}) => StepGenerator
+
+export { Logger, PublicAgentState }