@builder.io/ai-utils 0.71.1 → 0.72.0

package/package.json

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

package/src/codegen/investigation-context.d.ts

@@ -0,0 +1,22 @@
+import type { ContentMessage, MessageParam } from "../messages.js";
+export declare const MAX_TOOL_RESULT_CHARS = 8000;
+export declare const MAX_SYSTEM_PROMPT_CHARS = 60000;
+export declare const MAX_TRANSCRIPT_CHARS = 160000;
+export interface InvestigationEvent {
+    id: string;
+    hasError?: boolean;
+}
+export interface InvestigationCompletionJSON {
+    model?: string;
+    systemPrompt?: string;
+    messages?: MessageParam[];
+}
+export declare function serializeContentToBlocks(message: string | ContentMessage | undefined): string;
+export declare function messagesToText(messages: MessageParam[]): string;
+export declare function truncateToolResultsInTranscript(text: string): string;
+export interface BuildInvestigationSystemPromptInput {
+    event: InvestigationEvent;
+    completionJson: InvestigationCompletionJSON | undefined;
+}
+export declare function buildInvestigationSystemPrompt({ event, completionJson }: BuildInvestigationSystemPromptInput): string;
+export declare const SUGGESTED_QUESTIONS: readonly string[];

package/src/codegen/investigation-context.js

@@ -0,0 +1,147 @@
+export const MAX_TOOL_RESULT_CHARS = 8000;
+export const MAX_SYSTEM_PROMPT_CHARS = 60000;
+export const MAX_TRANSCRIPT_CHARS = 160000;
+function truncate(value, max) {
+    if (!value)
+        return "";
+    if (value.length <= max)
+        return value;
+    const removed = value.length - max;
+    return `${value.slice(0, max)}\n\n[truncated ${removed} chars]`;
+}
+// Block-serializer used by messagesToText and the dashboard LLM tab. Distinct
+// from the simpler text-only `getContentText` exported from messages.ts.
+export function serializeContentToBlocks(message) {
+    if (!message) {
+        return "";
+    }
+    if (typeof message === "string") {
+        return message;
+    }
+    if (!Array.isArray(message)) {
+        return "";
+    }
+    return message
+        .map((item) => {
+        var _a;
+        if (item.type === "text") {
+            return `<__llm_block__ type="text">\n${item.text}\n</__llm_block__>`;
+        }
+        else if (item.type === "image") {
+            return `<__llm_block__ type="image">${item.source.type === "base64"
+                ? ((_a = item.source.original_url) !== null && _a !== void 0 ? _a : "")
+                : item.source.url}</__llm_block__>`;
+        }
+        else if (item.type === "document") {
+            return `<__llm_block__ type="document" source_type="${item.source.type}" title="${item.title}">\n${item.source.type === "text" ? item.source.data : ""}\n</__llm_block__>`;
+        }
+        else if (item.type === "tool_use") {
+            return `<__llm_block__ type="tool_use" name="${item.name}" id="${item.id}">\n${JSON.stringify(item.input, null, 2)}\n</__llm_block__>`;
+        }
+        else if (item.type === "tool_result") {
+            return `<__llm_block__ type="tool_result" tool_use_id="${item.tool_use_id}" is_error="${item.is_error}">\n${serializeContentToBlocks(item.content)}\n</__llm_block__>`;
+        }
+        else if (item.type === "thinking") {
+            return `<__llm_block__ type="thinking" signature="${item.signature}">\n${item.thinking}\n</__llm_block__>`;
+        }
+        return "";
+    })
+        .join("\n\n");
+}
+export function messagesToText(messages) {
+    return messages
+        .map((message) => {
+        const content = serializeContentToBlocks(message.content);
+        return `<___llm_message___ role=${JSON.stringify(message.role)}>\n${content}\n</___llm_message___>`;
+    })
+        .join("\n\n");
+}
+export function truncateToolResultsInTranscript(text) {
+    // Truncate any oversized tool_result block content so a single huge tool
+    // result doesn't blow the context budget. tool_result bodies can contain
+    // nested __llm_block__ tags (recursive serialization), so we depth-track
+    // open/close to find the matching close tag rather than the first one.
+    const open = '<__llm_block__ type="tool_result"';
+    const anyOpen = "<__llm_block__";
+    const close = "</__llm_block__>";
+    let result = "";
+    let cursor = 0;
+    while (true) {
+        const start = text.indexOf(open, cursor);
+        if (start === -1) {
+            result += text.slice(cursor);
+            break;
+        }
+        result += text.slice(cursor, start);
+        const tagEnd = text.indexOf(">", start);
+        if (tagEnd === -1) {
+            result += text.slice(start);
+            break;
+        }
+        let depth = 1;
+        let scan = tagEnd + 1;
+        let blockEnd = -1;
+        while (scan < text.length) {
+            const nextOpen = text.indexOf(anyOpen, scan);
+            const nextClose = text.indexOf(close, scan);
+            if (nextClose === -1)
+                break;
+            if (nextOpen !== -1 && nextOpen < nextClose) {
+                depth++;
+                scan = nextOpen + anyOpen.length;
+                continue;
+            }
+            depth--;
+            if (depth === 0) {
+                blockEnd = nextClose;
+                break;
+            }
+            scan = nextClose + close.length;
+        }
+        if (blockEnd === -1) {
+            result += text.slice(start);
+            break;
+        }
+        const header = text.slice(start, tagEnd + 1);
+        const body = text.slice(tagEnd + 1, blockEnd);
+        const truncated = truncate(body, MAX_TOOL_RESULT_CHARS);
+        result += header + truncated + close;
+        cursor = blockEnd + close.length;
+    }
+    return result;
+}
+export function buildInvestigationSystemPrompt({ event, completionJson, }) {
+    var _a, _b;
+    const role = `You are a senior AI engineer helping debug a single codegen agent call.
+You have exactly the same context the engineer sees on the LLM tab for this
+event: the system prompt and the message transcript (with tool_use,
+tool_result, and thinking blocks). Be concise, specific, and critical.
+
+Ground every answer in the concrete data below: cite specific tool calls
+(by name + id), specific messages (by role + index), or system prompt
+sections. When you suggest improvements, propose concrete changes (e.g.
+"remove tool X", "add this instruction", "split this prompt section"). If
+the data does not support a claim, say so.`;
+    const header = `## Event\n\nid: ${event.id}\nmodel: ${(_a = completionJson === null || completionJson === void 0 ? void 0 : completionJson.model) !== null && _a !== void 0 ? _a : "(unknown)"}${event.hasError ? "\nstatus: ERROR" : ""}`;
+    // Use XML-style delimiters instead of triple-backtick fences: codegen
+    // transcripts often contain markdown code fences themselves which would
+    // otherwise close the outer block and corrupt the prompt.
+    const systemPromptBlock = `## System prompt (verbatim)\n\n<___event_system_prompt___>\n${truncate((_b = completionJson === null || completionJson === void 0 ? void 0 : completionJson.systemPrompt) !== null && _b !== void 0 ? _b : "(no system prompt)", MAX_SYSTEM_PROMPT_CHARS)}\n</___event_system_prompt___>`;
+    const transcriptText = (completionJson === null || completionJson === void 0 ? void 0 : completionJson.messages)
+        ? truncateToolResultsInTranscript(messagesToText(completionJson.messages))
+        : "(no messages)";
+    const transcriptBlock = `## Message transcript (tool_use / tool_result / thinking)\n\n<___event_transcript___>\n${truncate(transcriptText, MAX_TRANSCRIPT_CHARS)}\n</___event_transcript___>`;
+    const guidance = `## How to answer
+
+- Start with a 1-2 sentence direct answer.
+- Back it up with specific evidence (tool names, message indices, prompt phrases).
+- End with concrete improvement suggestions when applicable.`;
+    return [role, header, systemPromptBlock, transcriptBlock, guidance].join("\n\n");
+}
+export const SUGGESTED_QUESTIONS = [
+    "Why did this call fail or behave suboptimally?",
+    "Which tool calls were wasteful or redundant?",
+    "What context was missing that would have helped?",
+    "How could the system prompt be improved for this case?",
+    "Walk me through the agent's reasoning step by step.",
+];

package/src/codegen.d.ts

@@ -1331,6 +1331,15 @@ export declare const IDEDiagnosticsToolInputSchema: z.ZodObject<{
     file_path: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type IDEDiagnosticsToolInput = z.infer<typeof IDEDiagnosticsToolInputSchema>;
+export declare const GetCodegenEventToolInputSchema: z.ZodObject<{
+    event_id: z.ZodString;
+}, z.core.$strip>;
+export type GetCodegenEventToolInput = z.infer<typeof GetCodegenEventToolInputSchema>;
+export declare const ListCodegenSessionEventsToolInputSchema: z.ZodObject<{
+    session_or_event_id: z.ZodString;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type ListCodegenSessionEventsToolInput = z.infer<typeof ListCodegenSessionEventsToolInputSchema>;
 export declare const PullPrototypeToolInputSchema: z.ZodObject<{
     url: z.ZodString;
     project_id: z.ZodOptional<z.ZodString>;
@@ -1911,6 +1920,13 @@ export declare const CodeGenToolMapSchema: z.ZodObject<{
         draft: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>;
     GenerateDesignSystemAgentMd: z.ZodObject<{}, z.core.$strip>;
+    GetCodegenEvent: z.ZodObject<{
+        event_id: z.ZodString;
+    }, z.core.$strip>;
+    ListCodegenSessionEvents: z.ZodObject<{
+        session_or_event_id: z.ZodString;
+        limit: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
 }, z.core.$strip>;
 export type CodeGenToolMap = z.infer<typeof CodeGenToolMapSchema>;
 export declare const CodeGenToolsSchema: z.ZodEnum<{
@@ -1935,12 +1951,14 @@ export declare const CodeGenToolsSchema: z.ZodEnum<{
     FindMedia: "FindMedia";
     GenerateDesignSystemAgentMd: "GenerateDesignSystemAgentMd";
     GetAvailableRepos: "GetAvailableRepos";
+    GetCodegenEvent: "GetCodegenEvent";
     GetLastBrowserTest: "GetLastBrowserTest";
     GetScreenshot: "GetScreenshot";
     GetStyleInspiration: "GetStyleInspiration";
     Glob: "Glob";
     Grep: "Grep";
     IDEDiagnostics: "IDEDiagnostics";
+    ListCodegenSessionEvents: "ListCodegenSessionEvents";
     Media: "Media";
     MultiEdit: "MultiEdit";
     NavigatePreview: "NavigatePreview";
@@ -2652,12 +2670,14 @@ export declare const CodeGenInputOptionsSchema: z.ZodObject<{
         FindMedia: "FindMedia";
         GenerateDesignSystemAgentMd: "GenerateDesignSystemAgentMd";
         GetAvailableRepos: "GetAvailableRepos";
+        GetCodegenEvent: "GetCodegenEvent";
         GetLastBrowserTest: "GetLastBrowserTest";
         GetScreenshot: "GetScreenshot";
         GetStyleInspiration: "GetStyleInspiration";
         Glob: "Glob";
         Grep: "Grep";
         IDEDiagnostics: "IDEDiagnostics";
+        ListCodegenSessionEvents: "ListCodegenSessionEvents";
         Media: "Media";
         MultiEdit: "MultiEdit";
         NavigatePreview: "NavigatePreview";

package/src/codegen.js

@@ -1393,6 +1393,23 @@ export const IDEDiagnosticsToolInputSchema = z
     }),
 })
     .meta({ title: "IDEDiagnosticsToolInput" });
+export const GetCodegenEventToolInputSchema = z
+    .object({
+    event_id: z.string().meta({
+        description: "The codegen event ID to load (e.g. cgen-<eventId>).",
+    }),
+})
+    .meta({ title: "GetCodegenEventToolInput" });
+export const ListCodegenSessionEventsToolInputSchema = z
+    .object({
+    session_or_event_id: z.string().meta({
+        description: "A session ID or codegen event ID. When an event ID is given, its session is resolved first.",
+    }),
+    limit: z.number().optional().meta({
+        description: "Maximum number of events to return.",
+    }),
+})
+    .meta({ title: "ListCodegenSessionEventsToolInput" });
 export const PullPrototypeToolInputSchema = z
     .object({
     url: z.string().meta({
@@ -1499,6 +1516,8 @@ export const CodeGenToolMapSchema = z.object({
     ConnectMCP: ConnectMCPToolInputSchema,
     EnsurePR: EnsurePRToolInputSchema,
     GenerateDesignSystemAgentMd: GenerateDesignSystemAgentMdInputSchema,
+    GetCodegenEvent: GetCodegenEventToolInputSchema,
+    ListCodegenSessionEvents: ListCodegenSessionEventsToolInputSchema,
 });
 export const CodeGenToolsSchema = CodeGenToolMapSchema.keyof().meta({
     title: "CodeGenTools",

package/src/index.d.ts

@@ -6,6 +6,7 @@ export * from "./settings.js";
 export * from "./mapping.js";
 export * from "./common-schemas.js";
 export * from "./codegen.js";
+export * from "./codegen/investigation-context.js";
 export * from "./diff-hunks.js";
 export * from "./projects.js";
 export * from "./repo-indexing.js";

package/src/index.js

@@ -6,6 +6,7 @@ export * from "./settings.js";
 export * from "./mapping.js";
 export * from "./common-schemas.js";
 export * from "./codegen.js";
+export * from "./codegen/investigation-context.js";
 export * from "./diff-hunks.js";
 export * from "./projects.js";
 export * from "./repo-indexing.js";

package/src/projects.d.ts

@@ -886,6 +886,11 @@ export interface ProjectDatabase {
     createdAt: number;
     createdBy: string;
     lastActivityAt: number;
+    inactiveWarningSentAt?: number;
+    /** Set when the 60-day warning cannot be sent (no owner email); blocks further reclaim. */
+    inactiveWarningNoRecipientAt?: number;
+    inactiveSuspendedAt?: number;
+    inactiveDeletionScheduledAt?: number;
 }
 export interface BranchDatabase {
     ownerId: string;
@@ -914,6 +919,13 @@ export type DatabaseDeletion = (DatabaseDeletionBase & {
     neonBranchId?: never;
     neonProjectAllBranches: true;
 });
+/** Grace period before scheduled Neon deletions run (reconciler + schedule APIs). */
+export declare const NEON_DELETION_GRACE_PERIOD_MS: number;
+/**
+ * `DatabaseDeletion.reason` for inactive-project reclaim. Must stay aligned
+ * across the reconciler (writes) and activity touch (queries/deletes).
+ */
+export declare const INACTIVE_PROJECT_RECLAIM_REASON: "inactive-project-reclaim";
 /**
  * Get the state of a branch, checking `state` first and falling back to `deleted` for backwards compatibility.
  */

package/src/projects.js

@@ -45,6 +45,13 @@ export const EXAMPLE_OR_STARTER_REPOS_URLS = EXAMPLE_OR_STARTER_REPOS.map((repo)
 export const checkIsNewBranch = (branch) => {
     return "projectId" in branch;
 };
+/** Grace period before scheduled Neon deletions run (reconciler + schedule APIs). */
+export const NEON_DELETION_GRACE_PERIOD_MS = 30 * 24 * 60 * 60 * 1000;
+/**
+ * `DatabaseDeletion.reason` for inactive-project reclaim. Must stay aligned
+ * across the reconciler (writes) and activity touch (queries/deletes).
+ */
+export const INACTIVE_PROJECT_RECLAIM_REASON = "inactive-project-reclaim";
 /**
  * Get the state of a branch, checking `state` first and falling back to `deleted` for backwards compatibility.
  */