@builder.io/ai-utils 0.73.0 → 0.74.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@builder.io/ai-utils",
-  "version": "0.73.0",
+  "version": "0.74.0",
   "description": "Builder.io AI utils",
   "files": [
     "src"

package/src/codegen.d.ts

@@ -28,6 +28,11 @@ export declare const ProjectFileSchema: z.ZodObject<{
     virtual: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 export type ProjectFile = z.infer<typeof ProjectFileSchema>;
+export declare const CustomAgentInfoSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type CustomAgentInfo = z.infer<typeof CustomAgentInfoSchema>;
 export declare const CustomInstructionSchema: z.ZodObject<{
     id: z.ZodString;
     name: z.ZodString;
@@ -45,11 +50,16 @@ export declare const CustomInstructionSchema: z.ZodObject<{
     disableModelInvocation: z.ZodOptional<z.ZodBoolean>;
     userInvocable: z.ZodOptional<z.ZodBoolean>;
     scope: z.ZodOptional<z.ZodEnum<{
+        builtin: "builtin";
         plugin: "plugin";
         project: "project";
         user: "user";
     }>>;
     pluginName: z.ZodOptional<z.ZodString>;
+    ownedAgents: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
 }, z.core.$strip>;
 export type CustomInstruction = z.infer<typeof CustomInstructionSchema>;
 /** Reasoning effort level for LLM completions. */
@@ -64,11 +74,6 @@ export declare const ReasoningEffortSchema: z.ZodEnum<{
     xhigh: "xhigh";
 }>;
 export type ReasoningEffort = z.infer<typeof ReasoningEffortSchema>;
-export declare const CustomAgentInfoSchema: z.ZodObject<{
-    name: z.ZodString;
-    description: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
-export type CustomAgentInfo = z.infer<typeof CustomAgentInfoSchema>;
 /** Per-agent model overrides. String = fixed model, string[] = round-robin. */
 export declare const AgentModelOverridesSchema: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
 export type AgentModelOverrides = z.infer<typeof AgentModelOverridesSchema>;
@@ -1295,6 +1300,28 @@ export declare const SubmitPRReviewToolInputSchema: z.ZodObject<{
     }>>;
 }, z.core.$strip>;
 export type SubmitPRReviewToolInput = z.infer<typeof SubmitPRReviewToolInputSchema>;
+/**
+ * AddComment - a generic, UI-only tool for attaching a typed comment to the
+ * session. It never posts anywhere external; the service only validates the
+ * call and the dev-tools CLI emits a `comment-added` step from the tool input
+ * so the UI can render it. The `type` discriminates how the UI renders the
+ * comment (e.g. `"code-review"`), and `metadata` carries type-specific fields.
+ *
+ * Example (code-review skill):
+ *   addComment({
+ *     type: "code-review",
+ *     content: "Unawaited async call will fail in serverless",
+ *     metadata: { filePath: "src/x.ts", startLine: 264, endLine: 264, severity: "high" }
+ *   })
+ */
+export declare const AddCommentToolInputSchema: z.ZodObject<{
+    type: z.ZodString;
+    content: z.ZodString;
+    metadata: z.ZodOptional<z.ZodObject<{}, z.core.$loose>>;
+}, z.core.$strip>;
+export type AddCommentToolInput = Omit<z.infer<typeof AddCommentToolInputSchema>, "metadata"> & {
+    metadata?: AddedCommentMetadata;
+};
 export declare const ResolveQACommentsToolInputSchema: z.ZodObject<{
     thread_node_ids: z.ZodArray<z.ZodString>;
 }, z.core.$strip>;
@@ -1639,6 +1666,11 @@ export declare const CodeGenToolMapSchema: z.ZodObject<{
             looks_good: "looks_good";
         }>>;
     }, z.core.$strip>;
+    AddComment: z.ZodObject<{
+        type: z.ZodString;
+        content: z.ZodString;
+        metadata: z.ZodOptional<z.ZodObject<{}, z.core.$loose>>;
+    }, z.core.$strip>;
     ProposeConfig: z.ZodObject<{
         config: z.ZodObject<{
             projectOverview: z.ZodObject<{
@@ -1930,6 +1962,7 @@ export declare const CodeGenToolMapSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type CodeGenToolMap = z.infer<typeof CodeGenToolMapSchema>;
 export declare const CodeGenToolsSchema: z.ZodEnum<{
+    AddComment: "AddComment";
     AddMemory: "AddMemory";
     Agent: "Agent";
     ArchiveBranch: "ArchiveBranch";
@@ -2424,11 +2457,16 @@ export declare const CodeGenInputOptionsSchema: z.ZodObject<{
         disableModelInvocation: z.ZodOptional<z.ZodBoolean>;
         userInvocable: z.ZodOptional<z.ZodBoolean>;
         scope: z.ZodOptional<z.ZodEnum<{
+            builtin: "builtin";
             plugin: "plugin";
             project: "project";
             user: "user";
         }>>;
         pluginName: z.ZodOptional<z.ZodString>;
+        ownedAgents: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
     }, z.core.$strip>>>;
     customAgents: z.ZodOptional<z.ZodArray<z.ZodObject<{
         name: z.ZodString;
@@ -2649,6 +2687,7 @@ export declare const CodeGenInputOptionsSchema: z.ZodObject<{
     }, z.core.$strip>>;
     recommendedRoot: z.ZodOptional<z.ZodString>;
     enabledTools: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        AddComment: "AddComment";
         AddMemory: "AddMemory";
         Agent: "Agent";
         ArchiveBranch: "ArchiveBranch";
@@ -3194,6 +3233,37 @@ export interface GenerateCompletionStepGit {
     pendingValidation: boolean;
     unmergedFiles: string[];
 }
+/**
+ * A typed comment added to the session via the generic `AddComment` tool. The
+ * `commentType` mirrors the tool's `type` field (e.g. `"code-review"`) and
+ * drives how the UI renders it; `metadata` carries type-specific fields (for
+ * code review: `filePath`, `startLine`, optional `endLine`, optional
+ * `severity`).
+ */
+export interface AddedCommentOriginalSnippet {
+    filePath: string;
+    startLine: number;
+    endLine: number;
+    lines: string[];
+}
+export interface AddedCommentMetadata extends Record<string, unknown> {
+    originalSnippet?: AddedCommentOriginalSnippet;
+}
+export interface AddedComment {
+    commentType: string;
+    content: string;
+    metadata?: AddedCommentMetadata;
+}
+/**
+ * Emitted when a comment is added via the `AddComment` tool. The UI renders the
+ * comment based on its `commentType`. No external posting happens for this
+ * event — it is UI-only.
+ */
+export interface GenerateCompletionStepCommentAdded {
+    type: "comment-added";
+    id: string;
+    comment: AddedComment;
+}
 export interface GenerateCompletionStepClose {
     type: "close";
 }
@@ -3216,7 +3286,7 @@ export interface CustomInstructionDefinition {
     glob?: string;
     isSkill?: boolean;
     userInvocable?: boolean;
-    scope?: "project" | "user" | "plugin";
+    scope?: "project" | "user" | "plugin" | "builtin";
     pluginName?: string;
 }
 export interface GenerateCompletionStepSession {
@@ -3313,7 +3383,7 @@ export interface GenerateCompletionStepUpdateSetupValue {
     };
     reason: string;
 }
-export type GenerateCompletionStep = GenerateCompletionStepThinking | GenerateCompletionStepStart | GenerateCompletionStepDelta | GenerateCompletionStepUser | GenerateCompletionStepFile | GenerateCompletionStepDiff | GenerateCompletionStepTool | GenerateCompletionStepError | GenerateCompletionStepContinue | GenerateCompletionStepWaitForInput | GenerateCompletionStepAbort | GenerateCompletionStepDone | GenerateCompletionStepUserInput | GenerateCompletionStepText | GenerateCompletionStepRestore | GenerateCompletionStepState | GenerateCompletionStepStdio | GenerateCompletionStepSession | GenerateCompletionStepServerToolResult | GenerateCompletionStepGit | GenerateCompletionStepBuilderAction | GenerateCompletionStepLocalMCPAuthComplete | GenerateCompletionStepToolResult | GenerateCompletionStepFusionConfigPatch | GenerateCompletionStepToolCallRequest | GenerateCodeEventMCPStatus | GenerateCodeEventMCPAuthRequired | GenerateCompletionStepDevServerState | GenerateCompletionStepAgent | GenerateCompletionStepBatch | GenerateCompletionStepTerminals | GenerateCompletionStepMetadata | GenerateCompletionStepMessageQueue | GenerateCompletionStepProposeConfig | GenerateCompletionStepUpdateSetupValue | GenerateCompletionStepIde;
+export type GenerateCompletionStep = GenerateCompletionStepThinking | GenerateCompletionStepStart | GenerateCompletionStepDelta | GenerateCompletionStepUser | GenerateCompletionStepFile | GenerateCompletionStepDiff | GenerateCompletionStepTool | GenerateCompletionStepError | GenerateCompletionStepContinue | GenerateCompletionStepWaitForInput | GenerateCompletionStepAbort | GenerateCompletionStepDone | GenerateCompletionStepUserInput | GenerateCompletionStepText | GenerateCompletionStepRestore | GenerateCompletionStepState | GenerateCompletionStepStdio | GenerateCompletionStepSession | GenerateCompletionStepServerToolResult | GenerateCompletionStepGit | GenerateCompletionStepBuilderAction | GenerateCompletionStepLocalMCPAuthComplete | GenerateCompletionStepToolResult | GenerateCompletionStepFusionConfigPatch | GenerateCompletionStepToolCallRequest | GenerateCodeEventMCPStatus | GenerateCodeEventMCPAuthRequired | GenerateCompletionStepDevServerState | GenerateCompletionStepAgent | GenerateCompletionStepBatch | GenerateCompletionStepTerminals | GenerateCompletionStepMetadata | GenerateCompletionStepMessageQueue | GenerateCompletionStepProposeConfig | GenerateCompletionStepUpdateSetupValue | GenerateCompletionStepCommentAdded | GenerateCompletionStepIde;
 export interface ApplyActionsResult {
     filePath: string;
     addedLines: number;

package/src/codegen.js

@@ -22,6 +22,12 @@ export const ProjectFileSchema = z
     virtual: z.boolean().optional(),
 })
     .meta({ title: "ProjectFile" });
+export const CustomAgentInfoSchema = z
+    .object({
+    name: z.string(),
+    description: z.string().optional(),
+})
+    .meta({ title: "CustomAgentInfo" });
 export const CustomInstructionSchema = z
     .object({
     id: z.string(),
@@ -38,28 +44,31 @@ export const CustomInstructionSchema = z
     userInvocable: z.boolean().optional(),
     /**
      * Where this instruction was discovered. Drives precedence on name
-     * collision: `project` > `user` > `plugin`. Set by the discovery loader,
-     * not by the parsed file itself.
+     * collision: `project` > `user` > `plugin` > `builtin`. Set by the
+     * discovery loader, not by the parsed file itself. `builtin` marks
+     * product-level skills shipped with dev-tools.
      */
-    scope: z.enum(["project", "user", "plugin"]).optional(),
+    scope: z.enum(["project", "user", "plugin", "builtin"]).optional(),
     /**
      * Name of the plugin that contributed this instruction, if any. Set by
      * the plugin loader (Phase 2); always `undefined` for project-level and
      * user-level standalone files (Phase 1).
      */
     pluginName: z.string().optional(),
+    /**
+     * Subagents owned by this skill (name + description only). When the skill
+     * is invoked, the service registers these into the available agents so the
+     * model can spawn them within the same request's agent loop. The CLI holds
+     * the full agent definitions; only the metadata travels here. Used by
+     * built-in skills (e.g. `code-review`).
+     */
+    ownedAgents: z.array(CustomAgentInfoSchema).optional(),
 })
     .meta({ title: "CustomInstruction" });
 /** Reasoning effort level for LLM completions. */
 export const ReasoningEffortSchema = z
     .enum(["auto", "none", "minimal", "low", "medium", "high", "xhigh", "max"])
     .meta({ title: "ReasoningEffort" });
-export const CustomAgentInfoSchema = z
-    .object({
-    name: z.string(),
-    description: z.string().optional(),
-})
-    .meta({ title: "CustomAgentInfo" });
 /** Per-agent model overrides. String = fixed model, string[] = round-robin. */
 export const AgentModelOverridesSchema = z
     .record(z.string(), z.union([z.string(), z.array(z.string())]))
@@ -1329,6 +1338,36 @@ export const SubmitPRReviewToolInputSchema = z
     verdict: ReviewVerdictSchema.optional(),
 })
     .meta({ title: "SubmitPRReviewToolInput" });
+/**
+ * AddComment - a generic, UI-only tool for attaching a typed comment to the
+ * session. It never posts anywhere external; the service only validates the
+ * call and the dev-tools CLI emits a `comment-added` step from the tool input
+ * so the UI can render it. The `type` discriminates how the UI renders the
+ * comment (e.g. `"code-review"`), and `metadata` carries type-specific fields.
+ *
+ * Example (code-review skill):
+ *   addComment({
+ *     type: "code-review",
+ *     content: "Unawaited async call will fail in serverless",
+ *     metadata: { filePath: "src/x.ts", startLine: 264, endLine: 264, severity: "high" }
+ *   })
+ */
+export const AddCommentToolInputSchema = z
+    .object({
+    type: z.string().min(1).meta({
+        description: "Comment category that drives how the UI renders it, e.g. 'code-review'",
+    }),
+    content: z.string().min(1).meta({
+        description: "The comment body (plain text or markdown)",
+    }),
+    // `looseObject` (not `z.record`) so the JSON schema emits
+    // `additionalProperties` rather than `propertyNames`, which OpenAI's strict
+    // tool-schema mode rejects.
+    metadata: z.looseObject({}).optional().meta({
+        description: "Type-specific fields. For 'code-review': filePath (string), startLine (number), endLine (number, optional), severity ('high' | 'medium' | 'low'), and originalSnippet when available",
+    }),
+})
+    .meta({ title: "AddCommentToolInput" });
 export const ResolveQACommentsToolInputSchema = z
     .object({
     thread_node_ids: z.array(z.string()).meta({
@@ -1488,6 +1527,7 @@ export const CodeGenToolMapSchema = z.object({
     ReadMcpResource: ReadMcpResourceToolInputSchema,
     RecordFrame: RecordFrameToolInputSchema,
     SubmitPRReview: SubmitPRReviewToolInputSchema,
+    AddComment: AddCommentToolInputSchema,
     ProposeConfig: ProposeConfigToolInputSchema,
     UpdateSetupValue: UpdateSetupValueToolInputSchema,
     Exit: ExitToolInputSchema,