builder.io 1.17.27 → 1.17.28

package/types/cli/code-tools.d.ts

@@ -1,7 +1,8 @@
-import type { AccessResult, CodeGenPosition, CodeGenTools, CodegenTurn, ContentMessageItemToolResult, FusionConfig, GenerateCompletionStep, Permission, ProjectFile, UserSource, WorkspaceFolder } from "$/ai-utils";
+import type { AccessResult, CodeGenPosition, CodeGenTools, CodegenTurn, ContentMessageItemImage, ContentMessageItemText, ContentMessageItemToolResult, FusionConfig, GenerateCompletionStep, Permission, ProjectFile, UserSource, WorkspaceFolder } from "$/ai-utils";
 import type { DevToolsSys } from "../core";
 import { type DevServerOrchestrator } from "./launch/dev-server-orchestrator";
 import type { CodeGenEventEmitter } from "./codegen";
+import { CodeGenSession } from "./codegen";
 import type { Credentials } from "./credentials";
 import type { LocalMCPClientManager } from "./mcp-local";
 export interface LLMToolCalls {
@@ -11,7 +12,7 @@ export interface LLMToolCalls {
     abortController: AbortController;
 }
 export interface ToolResolution {
-    toolResult: string;
+    toolResult: string | (ContentMessageItemText | ContentMessageItemImage)[];
     isError: boolean;
     title?: string;
 }
@@ -34,6 +35,7 @@ export interface ToolContext extends Partial<FusionContext> {
     workingDirectory: string;
     allowedCommands: RegExp[];
     localMCPManager: LocalMCPClientManager | undefined;
+    session: CodeGenSession;
     getAllFiles: (options: {
         getDotFiles?: boolean;
         pattern?: string;

package/types/cli/codegen.d.ts

@@ -1,14 +1,16 @@
 import type { DevToolsSys } from "../types";
 import { type Credentials } from "./credentials";
-import type { CodegenFeedback, CodeGenToolMap, CodegenTurn, CustomInstruction, FusionConfig, GenerateCompletionState, GenerateCompletionStep, GenerateCompletionStepGit, GenerateUserMessage, SessionMode, UserContext, WorkspaceConfiguration, WorkspaceFolder, LoadWholeSessionOptions, LoadWholeSessionResult, LoadHistoryResult, CodeGenMode, ApplyActionsResult, PrivacyMode, CodeGenPosition, BackupGitRepoResult, PushChangesArgs, CodegenApiResult, CodegenApiTerminal, ConfigureDevOrchestratorOpts, ConfigureDevOrchestratorUpdates, RepoMetrics, CodegenApiCreateTerminal } from "$/ai-utils";
+import type { CodegenFeedback, CodeGenToolMap, CodegenTurn, CustomInstruction, FusionConfig, GenerateCompletionState, GenerateCompletionStep, GenerateCompletionStepGit, GenerateUserMessage, SessionMode, UserContext, UserSource, WorkspaceFolder, LoadWholeSessionOptions, LoadWholeSessionResult, LoadHistoryResult, CodeGenMode, ApplyActionsResult, PrivacyMode, CodeGenPosition, BackupGitRepoResult, PushChangesArgs, CodegenApiResult, CodegenApiTerminal, ConfigureDevOrchestratorOpts, ConfigureDevOrchestratorUpdates, RepoMetrics, SetImportantFilesToolInput, MCPServerConfig, CodegenApiCreateTerminal } from "$/ai-utils";
 import prettier from "prettier";
 import { type FusionContext, type ToolResolution } from "./code-tools";
+import { type SubAgent } from "./utils/agent-discovery";
 import EventEmitter from "node:events";
 import { type RunCommandOptions } from "./utils/git";
 export interface SessionContext {
     sessionId: string;
     turns: CodegenTurn[];
     customInstructions: CustomInstruction[];
+    customAgents: SubAgent[];
     userContext: UserContext;
     prettierConfig: prettier.Config | null;
     state: GenerateCompletionState;
@@ -27,6 +29,10 @@ export interface CodeGenSessionOptionsBase {
     mode: CodeGenMode;
     privacyMode?: PrivacyMode;
     builtInCustomInstructions?: CustomInstruction[];
+    builtInCustomAgents?: SubAgent[];
+    builtInMCPServerConfig?: MCPServerConfig;
+    autoImportLocalMCPs?: boolean;
+    systemPromptOverride?: string;
     fusionContext?: FusionContext;
     fusionConfig?: FusionConfig;
     workingDirectory?: string;
@@ -41,6 +47,15 @@ export interface CodeGenSessionOptionsInitialUrl extends CodeGenSessionOptionsBa
     initialUrl: string;
 }
 export type CodeGenSessionOptions = CodeGenSessionOptionsSession | CodeGenSessionOptionsInitialUrl;
+export interface SpawnAgentResult {
+    success: boolean;
+    response: string;
+    importantFiles: SetImportantFilesToolInput;
+    lastTurn?: CodegenTurn;
+}
+export { type SubAgent } from "./utils/agent-discovery";
+export { resolveModelShortcut } from "./utils/agent-parser";
+export { getCustomAgents } from "./utils/agent-discovery";
 export type CodeGenEventEmitter = EventEmitter<{
     step: [GenerateCompletionStep];
     idle: [];
@@ -61,6 +76,21 @@ export declare class CodeGenSession {
     loadWholeSession(opts?: LoadWholeSessionOptions): Promise<LoadWholeSessionResult>;
     loadMoreTurns(): Promise<CodegenTurn[]>;
     setCustomInstructions(instructions: CustomInstruction[]): Promise<void>;
+    setCustomAgents(agents: SubAgent[]): Promise<void>;
+    /**
+     * Spawn a named custom agent by ID or name
+     * @param agentNameOrId - The agent's name or ID
+     * @param options - Additional spawning options
+     * @returns SpawnAgentResult
+     */
+    spawnNamedAgent(agentName: string | undefined, options: {
+        prompt: string;
+        user: UserSource;
+        onStep?: (step: GenerateCompletionStep) => void;
+        signal?: AbortSignal;
+        maxCompletions?: number;
+        sessionId?: string;
+    }): Promise<SpawnAgentResult>;
     pushRepoV2(repoInfo: {
         repoFullName: string;
         repoUrl: string;
@@ -198,6 +228,18 @@ export declare class CodeGenSession {
     waitUntilState(state: GenerateCompletionState, timeout?: number): Promise<void>;
     clearSession(): Promise<void>;
     sendMessage(message: GenerateUserMessage): Promise<void>;
+    spawnAgent(options: {
+        prompt: string;
+        user: UserSource;
+        onStep?: (step: GenerateCompletionStep) => void;
+        signal?: AbortSignal;
+        maxCompletions?: number;
+        sessionId?: string;
+        tools?: string[];
+        model?: string;
+        mode?: CodeGenMode;
+        systemPrompt?: string;
+    }): Promise<SpawnAgentResult>;
     getTurns(): CodegenTurn[];
     getSessionContext(): SessionContext;
     runSetupCommand(): Promise<import("$/ai-utils").SetupCommandResult | undefined>;
@@ -363,25 +405,3 @@ export declare class CodeGenSession {
      */
     private getDiffFromParentBranch;
 }
-export declare function getUserContext(sys: DevToolsSys, gitWorkingDirectory?: string): Promise<UserContext>;
-export declare function makeAsyncIterator<T>(): readonly [AsyncGenerator<T, void, void>, (event: T) => void, () => void];
-/**
- * Loads a workspace configuration from a JSON file
- * @param sys DevToolsSys instance
- * @param workspaceFile Path to the workspace JSON file
- * @returns The workspace configuration and working directory
- */
-export declare function loadWorkspace(sys: DevToolsSys, workspaceFile: string): Promise<{
-    workspace: WorkspaceConfiguration;
-    workingDirectory: string;
-}>;
-export declare function keepAlive(): () => void;
-export declare class BashError extends Error {
-    readonly code: number | string | undefined;
-    readonly stdout: string;
-    readonly stderr: string;
-    readonly command: string;
-    constructor(command: string, code: number | string | undefined, stdout: string, stderr: string, opts?: {
-        cause?: Error;
-    });
-}

package/types/cli/mcp-local.d.ts

@@ -8,7 +8,7 @@
  * - Tools are prefixed with server name: `mcp__servername__toolname`
  * - This prevents conflicts with built-in tools and other MCP tools
  */
-import type { MCPClientStatus } from "$/ai-utils";
+import type { MCPClientStatus, MCPServerConfig } from "$/ai-utils";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import type { DevToolsSys } from "../core";
 import { type ChildProcess } from "child_process";
@@ -76,6 +76,4 @@ export declare function applyEnvSubstitution(serverConfig: Omit<MCPServerStdioDe
  * Servers from fusionConfig will be merged with servers from mcp.json
  * If a server with the same name exists in both, fusionConfig takes precedence
  */
-export declare function loadMCPConfig(sys: DevToolsSys, workingDirectory: string, fusionConfig?: {
-    mcpServers?: Record<string, Omit<MCPServerStdioDefinition, "name">>;
-}): Promise<MCPServerStdioDefinition[]>;
+export declare function loadMCPConfig(sys: DevToolsSys, workingDirectory: string, serverConfigs: MCPServerConfig, autoImportLocalMCPs: boolean): Promise<MCPServerStdioDefinition[]>;

package/types/cli/utils/agent-discovery.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Agent discovery utilities
+ * Handles finding and loading custom agent definitions from the filesystem
+ */
+import type { DevToolsSys } from "../../types";
+import { type SubAgent } from "./agent-parser";
+export type { SubAgent };
+/**
+ * Get custom agents from the filesystem
+ * Searches for agent definitions in .claude/agents, .builder/agents, and .cursor/agents
+ * @param sys - System utilities
+ * @param projectDir - Project directory (used for relative paths)
+ * @param currentDir - Starting directory for search
+ * @param rootDir - Root directory to stop search
+ * @returns Array of discovered agents
+ */
+export declare function getCustomAgents({ sys, projectDir, currentDir, rootDir, }: {
+    sys: DevToolsSys;
+    projectDir: string;
+    currentDir: string;
+    rootDir: string;
+}): Promise<SubAgent[]>;

package/types/cli/utils/agent-parser.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Agent definition parsing utilities
+ * Handles parsing of custom agent definition files
+ */
+import type { CodeGenMode } from "$/ai-utils";
+export interface SubAgent {
+    name: string;
+    description?: string;
+    systemPrompt?: string;
+    tools?: string[];
+    model?: string;
+    mode?: CodeGenMode;
+    filePath?: string;
+}
+/**
+ * Resolves model shortcut to full model name
+ * @param modelOrShortcut - Model name or shortcut
+ * @returns Resolved model name or undefined
+ */
+export declare function resolveModelShortcut(modelOrShortcut?: string): string | undefined;
+/**
+ * Parses an agent definition file (Markdown with YAML frontmatter)
+ * Expected format (following Claude Code sub-agents format):
+ * ```yaml
+ * ---
+ * name: Agent Name
+ * description: Description of what the agent does
+ * model: sonnet  # Optional: supports shortcuts like sonnet, opus, haiku, mini
+ * tools:         # Optional: list of tools to enable
+ *   - Read
+ *   - Grep
+ *   - WebSearch
+ * mode: quality-v4-agent  # Optional: agent mode
+ * ---
+ * System prompt content here (Markdown)
+ * ```
+ * @param fileContent - The raw file content
+ * @param filePath - The file path (used for fallback name)
+ * @returns Parsed SubAgent or null if parsing fails
+ */
+export declare function parseAgentFile(fileContent: string, filePath: string): SubAgent | null;

package/types/cli/utils/agent-parser.test.d.ts

@@ -0,0 +1 @@
+export {};

package/types/cli/utils/browser-testing-agent.d.ts

@@ -0,0 +1,2 @@
+import type { CustomAgentDefinition } from "$/ai-utils";
+export declare const TEST_AGENT: CustomAgentDefinition;

package/types/cli/utils/codegen-utils.d.ts

@@ -0,0 +1,70 @@
+import type { DevToolsSys } from "../../core";
+import { type Credentials } from "../credentials";
+export { getCustomInstructions } from "./rules-discovery";
+import type { CodeGenInputOptions, CodegenSetLastCompletion, CodegenTurn, GenerateCodeEvent, GenerateUserMessage, GetSessionTurnsResult, UserContext, WorkspaceConfiguration, EnvironmentVariable, PushChangesArgs } from "$/ai-utils";
+import type { SessionContext } from "../codegen";
+export declare const DEFAULT_MAX_COMPLETIONS = 30;
+/**
+ * Merges and deduplicates items by name.
+ * Built-in items come first, discovered items can override them by name.
+ * @param builtIn - Built-in items
+ * @param discovered - Discovered items from project
+ * @returns Deduplicated array with discovered overriding built-in
+ */
+export declare function mergeByName<T extends {
+    name: string;
+}>(builtIn: T[], discovered: T[]): T[];
+export declare function getLastGoodTurn(sessionContext: SessionContext): CodegenTurn | undefined;
+export declare function getLastUserTurn(sessionContext: SessionContext): CodegenTurn | undefined;
+export declare function getLastApplyResultsTurn(sessionContext: SessionContext): CodegenTurn | undefined;
+export declare function getLastOne<T>(array: T[]): T | undefined;
+export declare function inPlaceRemovePendingTurns(turns: CodegenTurn[]): void;
+export declare function restoreConsumedCredit(sys: DevToolsSys, credentials: Credentials, sessionId: string, restoreCredits: number): Promise<void>;
+/**
+ * Analyzes the payload to identify what's making it large
+ */
+export declare function analyzePayloadBreakdown(body: CodeGenInputOptions, jsonString: string): Record<string, any>;
+export declare function completionStream(sys: DevToolsSys, credentials: Credentials, body: CodeGenInputOptions, signal: AbortSignal): AsyncGenerator<GenerateCodeEvent, void, unknown>;
+export declare function codegenEndpoint(sys: DevToolsSys, credentials: Credentials, endpoint: string, body: Record<string, any>): Promise<boolean>;
+export declare function setLastCompletionOfSession(sys: DevToolsSys, credentials: Credentials, data: CodegenSetLastCompletion, _verbose: boolean): Promise<boolean>;
+export declare function getTurnsBySessionId(sys: DevToolsSys, credentials: Credentials, sessionId: string, linear: boolean, completionIdCursor?: string): Promise<GetSessionTurnsResult>;
+export declare const parseCLIURL: (url: string | undefined) => {
+    id: undefined;
+    isInitial: boolean;
+} | {
+    isInitial: boolean;
+    id: string;
+};
+export declare function getUserContext(sys: DevToolsSys, gitWorkingDirectory?: string): Promise<UserContext>;
+export declare function makeAsyncIterator<T>(): readonly [AsyncGenerator<T, void, void>, (event: T) => void, () => void];
+export declare function isAGENTSFile(filePath: string): boolean;
+export declare function isBaseImportantFile(filePath: string): boolean;
+export declare function hasBuildError(text: string): boolean;
+/**
+ * Loads a workspace configuration from a JSON file
+ * @param sys DevToolsSys instance
+ * @param workspaceFile Path to the workspace JSON file
+ * @returns The workspace configuration and working directory
+ */
+export declare function loadWorkspace(sys: DevToolsSys, workspaceFile: string): Promise<{
+    workspace: WorkspaceConfiguration;
+    workingDirectory: string;
+}>;
+export declare function mergeUserMessages(currentMessage: GenerateUserMessage, newMessage: GenerateUserMessage): GenerateUserMessage;
+export declare function keepAlive(): () => void;
+export declare function parseAheadBehind(line: string): {
+    ahead: number;
+    behind: number;
+};
+export declare class BashError extends Error {
+    readonly code: number | string | undefined;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly command: string;
+    constructor(command: string, code: number | string | undefined, stdout: string, stderr: string, opts?: {
+        cause?: Error;
+    });
+}
+export declare function mergeEnvironmentVariables(envVariables: EnvironmentVariable[], extraEnvVariables: EnvironmentVariable[]): EnvironmentVariable[];
+export declare function processPushChangesArgs(opts: PushChangesArgs): import("$/ai-utils").PushChangesOptions;
+export declare function getErrorMessage(err: unknown): string;

package/types/cli/utils/rules-discovery.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Custom instruction/rules discovery utilities
+ * Handles finding and loading custom instructions from the filesystem
+ */
+import type { DevToolsSys } from "../../types";
+import type { CustomInstruction } from "$/ai-utils";
+/**
+ * Get custom instructions from the filesystem
+ * Searches for instruction files in:
+ * - .cursor/rules/
+ * - .builder/rules/
+ * - .cursorrules, .builderrules, .windsurfrules
+ * - .github/copilot-instructions.md
+ *
+ * @param sys - System utilities
+ * @param projectDir - Project directory (used for relative paths)
+ * @param currentDir - Starting directory for search
+ * @param rootDir - Root directory to stop search
+ * @returns Array of discovered custom instructions
+ */
+export declare function getCustomInstructions({ sys, projectDir, currentDir, rootDir, }: {
+    sys: DevToolsSys;
+    projectDir: string;
+    currentDir: string;
+    rootDir: string;
+}): Promise<CustomInstruction[]>;

package/types/cli/utils/rules-parser.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Custom instruction/rules parsing utilities
+ * Handles parsing of custom instruction files (.mdc, .cursorrules, etc.)
+ */
+import type { CustomInstruction } from "$/ai-utils";
+/**
+ * Parse a custom instruction file
+ * Supports both:
+ * - .mdc files with YAML frontmatter
+ * - Plain text files (.cursorrules, .builderrules, etc.)
+ *
+ * @param fileContent - Raw file content
+ * @param filePath - File path (for generating name and id)
+ * @param hashFunction - Optional hash function for generating unique IDs
+ * @returns Parsed CustomInstruction or null
+ */
+export declare function parseCustomInstructionFile(fileContent: string, filePath: string, hashFunction?: (content: string) => string): CustomInstruction | null;

package/types/cli/utils/rules-parser.test.d.ts

@@ -0,0 +1 @@
+export {};

package/types/cli/utils/yaml-frontmatter.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Generic YAML frontmatter parser for Markdown files
+ * Supports both simple key-value pairs and arrays
+ */
+export interface YamlFrontmatterResult<T = Record<string, any>> {
+    frontmatter: T;
+    body: string;
+}
+/**
+ * Checks if content has YAML frontmatter
+ */
+export declare function hasYamlFrontmatter(content: string): boolean;
+/**
+ * Parses YAML frontmatter from a string
+ * Handles simple YAML: key-value pairs, arrays, and comments
+ */
+export declare function parseYamlFrontmatter(yamlContent: string): Record<string, any>;
+/**
+ * Extracts YAML frontmatter and body from Markdown content
+ * @param content - The raw Markdown content with frontmatter
+ * @returns Object with frontmatter and body, or null if no frontmatter found
+ */
+export declare function extractYamlFrontmatter(content: string): {
+    frontmatterContent: string;
+    body: string;
+} | null;
+/**
+ * Parse Markdown file with YAML frontmatter
+ * @param content - The raw file content
+ * @returns Parsed frontmatter and body
+ */
+export declare function parseMarkdownWithYaml<T = Record<string, any>>(content: string): YamlFrontmatterResult<T>;

package/types/cli/utils/yaml-frontmatter.test.d.ts

@@ -0,0 +1 @@
+export {};