@builder.io/ai-utils 0.71.1 → 0.73.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@builder.io/ai-utils",
-  "version": "0.71.1",
+  "version": "0.73.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";
@@ -3540,12 +3560,10 @@ export interface UserInput {
     /** @deprecated */
     repair?: boolean;
 }
-export interface CodegenTurn {
-    state: "running" | "done" | "error";
+interface CodegenTurnBase {
     unixTime: number;
     completionId: string;
     title: string;
-    nextUrl: string | undefined;
     user: UserSource;
     creditsUsed: number;
     actions: ActionItem[];
@@ -3557,7 +3575,34 @@ export interface CodegenTurn {
     lastCommit: GitSnapshot | undefined;
     cachedToolResults?: ContentMessageItemToolResult[];
     autoContinue: boolean;
+    /**
+     * Only set on synthetic per-user-message checkpoints (the non-linear
+     * `getSessionTurns` result). `completionId` always stays the checkpoint's
+     * own identity — for these synthetic turns, the user message's id — which is
+     * exactly what restoring "before this point" needs (the factual commit at
+     * that moment). `finalCompletionId` separately carries the last agent turn in
+     * the message's range that holds the post-message commit (`afterCommit`), for
+     * callers that want to restore to the "after" state. Undefined for ordinary
+     * (linear) turns.
+     */
+    finalCompletionId?: string;
+}
+/**
+ * A completed turn. Invariant: a `done` turn ALWAYS has a `nextUrl` (the
+ * continuation pointer the server emits on the `done` event / persists as the
+ * session's last completion). Encoded in the type so `state === "done"` narrows
+ * `nextUrl` to `string` — restore/anchor logic can rely on it.
+ */
+export interface CodegenTurnDone extends CodegenTurnBase {
+    state: "done";
+    nextUrl: string;
+}
+/** A turn that is still running, or errored before completing. */
+export interface CodegenTurnPending extends CodegenTurnBase {
+    state: "running" | "error";
+    nextUrl: string | undefined;
 }
+export type CodegenTurn = CodegenTurnDone | CodegenTurnPending;
 export interface GetSessionTurnsResult {
     turns: CodegenTurn[];
     allIds: string[];
@@ -4636,3 +4681,4 @@ export interface SessionData {
     numNormalUserMessages: number;
     metadata?: Record<string, any>;
 }
+export {};

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/design-systems.d.ts

@@ -35,10 +35,6 @@ export interface GenerateDesignSystemFormFields {
  */
 export declare const GITHUB_REPO_URL_REGEX: RegExp;
 export interface GenerateDesignSystemRequest extends GenerateDesignSystemFormFields {
-    /**
-     * Mixed list of uploaded files in any order. Sent as repeated
-     * `attachments` fields in the multipart body.
-     */
     attachments: File[];
 }
 export interface GenerateDesignSystemResponse {
@@ -58,18 +54,75 @@ export interface GenerateDesignSystemErrorResponse {
 export declare const GENERATE_DESIGN_SYSTEM_MAX_FILE_BYTES: number;
 export declare const GENERATE_DESIGN_SYSTEM_MAX_ATTACHMENTS = 50;
 export declare const GENERATE_DESIGN_SYSTEM_MIN_ATTACHMENTS = 1;
+export declare const generateDesignSystemBodySchema: z.ZodObject<{
+    projectName: z.ZodOptional<z.ZodString>;
+    devToolsVersion: z.ZodOptional<z.ZodString>;
+    selection: z.ZodOptional<z.ZodPreprocess<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>>;
+    githubRepoUrl: z.ZodOptional<z.ZodString>;
+    connectedProjectId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type GenerateDesignSystemBody = z.infer<typeof generateDesignSystemBodySchema>;
 /**
- * Validation for non-file fields posted alongside the multipart upload.
- * Files are parsed out of the body by multer before this schema runs.
+ * Signed-URL upload flow.
  *
- * The inferred type matches `GenerateDesignSystemFormFields` so the wire
- * contract stays in lockstep with the shared type.
+ * Clients no longer post `.fig` bytes through the service (Cloud Run caps
+ * request bodies at 32 MiB). Instead they call `upload/start` to get a
+ * temporary signed resumable-upload URL per attachment, stream the bytes
+ * directly to GCS, then call `/generate` with the returned upload tokens.
+ * See `tech-specs/signed-url-figma-upload`.
  */
-export declare const generateDesignSystemBodySchema: z.ZodObject<{
+/** A single attachment the client declares when starting an upload. */
+export declare const uploadStartAttachmentSchema: z.ZodObject<{
+    name: z.ZodString;
+    mimetype: z.ZodString;
+    declaredSize: z.ZodNumber;
+}, z.core.$strip>;
+export type UploadStartAttachment = z.infer<typeof uploadStartAttachmentSchema>;
+/** Request body for `POST /design-systems/v1/upload/start`. */
+export declare const uploadStartBodySchema: z.ZodObject<{
+    attachments: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        mimetype: z.ZodString;
+        declaredSize: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type UploadStartBody = z.infer<typeof uploadStartBodySchema>;
+/**
+ * Claims encoded inside a signed `uploadToken`. Bound to the GCS object at
+ * `upload/start` and verified at `/generate`, so a client cannot point the
+ * decode worker at an object it did not upload.
+ */
+export declare const uploadTokenPayloadSchema: z.ZodObject<{
+    jobId: z.ZodString;
+    gcsObject: z.ZodString;
+    ownerId: z.ZodString;
+    mimetype: z.ZodString;
+    originalName: z.ZodString;
+    idx: z.ZodNumber;
+}, z.core.$strip>;
+export type UploadTokenPayload = z.infer<typeof uploadTokenPayloadSchema>;
+export interface UploadStartResponseItem {
+    idx: number;
+    /** Signed URL the client POSTs to (with `x-goog-resumable: start`) to begin the resumable upload. */
+    uploadUrl: string;
+    /** Opaque signed token the client passes back to `/generate`. */
+    uploadToken: string;
+}
+export interface UploadStartResponse {
+    jobId: string;
+    uploads: UploadStartResponseItem[];
+}
+/**
+ * Request body for the signed-URL variant of `POST /design-systems/v1/generate`.
+ * Same non-file fields as the legacy multipart form, plus the `uploads`
+ * tokens returned by `upload/start` (one per attachment).
+ */
+export declare const generateDesignSystemRequestSchema: z.ZodObject<{
     projectName: z.ZodOptional<z.ZodString>;
     devToolsVersion: z.ZodOptional<z.ZodString>;
     selection: z.ZodOptional<z.ZodPreprocess<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>>;
     githubRepoUrl: z.ZodOptional<z.ZodString>;
     connectedProjectId: z.ZodOptional<z.ZodString>;
+    uploads: z.ZodArray<z.ZodString>;
 }, z.core.$strip>;
-export type GenerateDesignSystemBody = z.infer<typeof generateDesignSystemBodySchema>;
+export type GenerateDesignSystemRequestBody = z.infer<typeof generateDesignSystemRequestSchema>;

package/src/design-systems.js

@@ -8,13 +8,6 @@ export const GITHUB_REPO_URL_REGEX = /^https:\/\/github\.com\/[A-Za-z0-9_.-]+\/[
 export const GENERATE_DESIGN_SYSTEM_MAX_FILE_BYTES = 2 * 1024 * 1024 * 1024;
 export const GENERATE_DESIGN_SYSTEM_MAX_ATTACHMENTS = 50;
 export const GENERATE_DESIGN_SYSTEM_MIN_ATTACHMENTS = 1;
-/**
- * Validation for non-file fields posted alongside the multipart upload.
- * Files are parsed out of the body by multer before this schema runs.
- *
- * The inferred type matches `GenerateDesignSystemFormFields` so the wire
- * contract stays in lockstep with the shared type.
- */
 export const generateDesignSystemBodySchema = z.object({
     projectName: z.string().trim().min(1).max(200).optional(),
     devToolsVersion: z.string().trim().min(1).max(64).optional(),
@@ -40,3 +33,54 @@ export const generateDesignSystemBodySchema = z.object({
         .optional(),
     connectedProjectId: z.string().trim().min(1).max(128).optional(),
 });
+/**
+ * Signed-URL upload flow.
+ *
+ * Clients no longer post `.fig` bytes through the service (Cloud Run caps
+ * request bodies at 32 MiB). Instead they call `upload/start` to get a
+ * temporary signed resumable-upload URL per attachment, stream the bytes
+ * directly to GCS, then call `/generate` with the returned upload tokens.
+ * See `tech-specs/signed-url-figma-upload`.
+ */
+/** A single attachment the client declares when starting an upload. */
+export const uploadStartAttachmentSchema = z.object({
+    name: z.string().trim().min(1).max(512),
+    mimetype: z.string().trim().min(1).max(255),
+    declaredSize: z
+        .number()
+        .int()
+        .positive()
+        .max(GENERATE_DESIGN_SYSTEM_MAX_FILE_BYTES),
+});
+/** Request body for `POST /design-systems/v1/upload/start`. */
+export const uploadStartBodySchema = z.object({
+    attachments: z
+        .array(uploadStartAttachmentSchema)
+        .min(GENERATE_DESIGN_SYSTEM_MIN_ATTACHMENTS)
+        .max(GENERATE_DESIGN_SYSTEM_MAX_ATTACHMENTS),
+});
+/**
+ * Claims encoded inside a signed `uploadToken`. Bound to the GCS object at
+ * `upload/start` and verified at `/generate`, so a client cannot point the
+ * decode worker at an object it did not upload.
+ */
+export const uploadTokenPayloadSchema = z.object({
+    jobId: z.string().min(1),
+    gcsObject: z.string().min(1),
+    ownerId: z.string().min(1),
+    mimetype: z.string().min(1),
+    originalName: z.string().min(1),
+    idx: z.number().int().nonnegative(),
+});
+/**
+ * Request body for the signed-URL variant of `POST /design-systems/v1/generate`.
+ * Same non-file fields as the legacy multipart form, plus the `uploads`
+ * tokens returned by `upload/start` (one per attachment).
+ */
+export const generateDesignSystemRequestSchema = z.object({
+    ...generateDesignSystemBodySchema.shape,
+    uploads: z
+        .array(z.string().min(1))
+        .min(GENERATE_DESIGN_SYSTEM_MIN_ATTACHMENTS)
+        .max(GENERATE_DESIGN_SYSTEM_MAX_ATTACHMENTS),
+});

package/src/events.d.ts

@@ -1039,6 +1039,8 @@ export type FigmaDecodeJobV1 = FusionEventVariant<"figma.decode.job", {
     projectId: string;
     projectName: string;
     figmaName: string;
+    /** Design-system record this job feeds; updated with the branch once created. */
+    designSystemId?: string;
     /**
      * GCS object paths (relative to the configured bucket) of every attachment
      * uploaded for this job. The worker streams these back down, runs

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.
  */