busabase-sdk 0.30.1 → 0.40.1

package/dist/airapp.d.ts

@@ -1,4 +1,4 @@
-import { t as BusabaseClient } from "./client-DJmL8Jl_.js";
+import { t as BusabaseClient } from "./client-DbETz_5k.js";
 //#region src/airapp.d.ts
 type NodeChangeRequestInput = Parameters<BusabaseClient["nodes"]["createChangeRequest"]>[0];
 type NodeOperationInput = NodeChangeRequestInput["operations"][number];

package/dist/{client-DJmL8Jl_.d.ts → client-DbETz_5k.d.ts}

@@ -319,6 +319,10 @@ declare const NodeIconSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
 type NodeIcon = z.infer<typeof NodeIconSchema>;
 //#endregion
 //#region ../../packages/busabase-contract/src/contract/schemas.d.ts
+/** @see nodeSettingsSchema — declared here so `NodeOutput` can reference it. */
+type NodeSettings = {
+  airappEngine?: "browser" | "local" | "remote" | null;
+};
 interface NodeOutput {
   id: string;
   parentId: string | null;
@@ -338,6 +342,15 @@ interface NodeOutput {
   metadata: Record<string, unknown> & {
     version?: string;
   };
+  /**
+   * System settings the product DOES read and act on — the opposite of
+   * `metadata` above, and separate for that reason.
+   *
+   * Written only by `PATCH /nodes/{nodeId}/settings`, whose input is a closed
+   * schema; the generic metadata endpoint cannot address it. See
+   * `nodeSettingsSchema`.
+   */
+  settings?: NodeSettings;
   /**
    * This node's OWN declared visibility, or null when it simply inherits from
    * its ancestors. Access control, so it is a real column rather than a
@@ -1628,6 +1641,113 @@ declare const cloudContract: {
       nodeId: z.ZodString;
       metadata: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     }, z.core.$strip>, z.ZodType<NodeOutput, unknown, z.core.$ZodTypeInternals<NodeOutput, unknown>>, import("@orpc/contract").MergedErrorMap<Record<never, never>, Record<never, never>>, Record<never, never>>;
+    updateSettings: import("@orpc/contract").ContractProcedure<z.ZodObject<{
+      nodeId: z.ZodString;
+      settings: z.ZodObject<{
+        airappEngine: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+          browser: "browser";
+          local: "local";
+          remote: "remote";
+        }>>>;
+      }, z.core.$strict>;
+    }, z.core.$strip>, z.ZodType<NodeOutput, unknown, z.core.$ZodTypeInternals<NodeOutput, unknown>>, import("@orpc/contract").MergedErrorMap<Record<never, never>, Record<never, never>>, Record<never, never>>;
+    getAgentPrompts: import("@orpc/contract").ContractProcedure<z.ZodObject<{
+      nodeId: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+      nodeId: z.ZodString;
+      agentPrompts: z.ZodNullable<z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        intent: z.ZodOptional<z.ZodEnum<{
+          change: "change";
+          "read-only": "read-only";
+        }>>;
+        label: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodEnum<{
+          de: "de";
+          en: "en";
+          es: "es";
+          fr: "fr";
+          ja: "ja";
+          ko: "ko";
+          pt: "pt";
+          "zh-CN": "zh-CN";
+          "zh-TW": "zh-TW";
+        }> & z.core.$partial, z.ZodString>]>;
+        body: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodEnum<{
+          de: "de";
+          en: "en";
+          es: "es";
+          fr: "fr";
+          ja: "ja";
+          ko: "ko";
+          pt: "pt";
+          "zh-CN": "zh-CN";
+          "zh-TW": "zh-TW";
+        }> & z.core.$partial, z.ZodString>]>;
+      }, z.core.$strip>>>;
+    }, z.core.$strip>, import("@orpc/contract").MergedErrorMap<Record<never, never>, Record<never, never>>, Record<never, never>>;
+    updateAgentPrompts: import("@orpc/contract").ContractProcedure<z.ZodObject<{
+      nodeId: z.ZodString;
+      agentPrompts: z.ZodNullable<z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        intent: z.ZodOptional<z.ZodEnum<{
+          change: "change";
+          "read-only": "read-only";
+        }>>;
+        label: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodEnum<{
+          de: "de";
+          en: "en";
+          es: "es";
+          fr: "fr";
+          ja: "ja";
+          ko: "ko";
+          pt: "pt";
+          "zh-CN": "zh-CN";
+          "zh-TW": "zh-TW";
+        }> & z.core.$partial, z.ZodString>]>;
+        body: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodEnum<{
+          de: "de";
+          en: "en";
+          es: "es";
+          fr: "fr";
+          ja: "ja";
+          ko: "ko";
+          pt: "pt";
+          "zh-CN": "zh-CN";
+          "zh-TW": "zh-TW";
+        }> & z.core.$partial, z.ZodString>]>;
+      }, z.core.$strip>>>;
+    }, z.core.$strip>, z.ZodObject<{
+      nodeId: z.ZodString;
+      agentPrompts: z.ZodNullable<z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        intent: z.ZodOptional<z.ZodEnum<{
+          change: "change";
+          "read-only": "read-only";
+        }>>;
+        label: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodEnum<{
+          de: "de";
+          en: "en";
+          es: "es";
+          fr: "fr";
+          ja: "ja";
+          ko: "ko";
+          pt: "pt";
+          "zh-CN": "zh-CN";
+          "zh-TW": "zh-TW";
+        }> & z.core.$partial, z.ZodString>]>;
+        body: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodEnum<{
+          de: "de";
+          en: "en";
+          es: "es";
+          fr: "fr";
+          ja: "ja";
+          ko: "ko";
+          pt: "pt";
+          "zh-CN": "zh-CN";
+          "zh-TW": "zh-TW";
+        }> & z.core.$partial, z.ZodString>]>;
+      }, z.core.$strip>>>;
+    }, z.core.$strip>, import("@orpc/contract").MergedErrorMap<Record<never, never>, Record<never, never>>, Record<never, never>>;
     updateContent: import("@orpc/contract").ContractProcedure<z.ZodObject<{
       nodeId: z.ZodString;
       content: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -2729,8 +2849,10 @@ declare const cloudContract: {
         "drive.created": "drive.created";
         "field.created": "field.created";
         "file.created": "file.created";
+        "node.agent_prompts_updated": "node.agent_prompts_updated";
         "node.metadata_updated": "node.metadata_updated";
         "node.purged": "node.purged";
+        "node.settings_updated": "node.settings_updated";
         "record.viewed": "record.viewed";
         "skill.created": "skill.created";
       }>;
@@ -2784,8 +2906,10 @@ declare const cloudContract: {
         "drive.created": "drive.created";
         "field.created": "field.created";
         "file.created": "file.created";
+        "node.agent_prompts_updated": "node.agent_prompts_updated";
         "node.metadata_updated": "node.metadata_updated";
         "node.purged": "node.purged";
+        "node.settings_updated": "node.settings_updated";
         "record.viewed": "record.viewed";
         "skill.created": "skill.created";
       }>;
@@ -2815,8 +2939,10 @@ declare const cloudContract: {
         "drive.created": "drive.created";
         "field.created": "field.created";
         "file.created": "file.created";
+        "node.agent_prompts_updated": "node.agent_prompts_updated";
         "node.metadata_updated": "node.metadata_updated";
         "node.purged": "node.purged";
+        "node.settings_updated": "node.settings_updated";
         "record.viewed": "record.viewed";
         "skill.created": "skill.created";
       }>;
@@ -3949,8 +4075,10 @@ declare const cloudContract: {
             "drive.created": "drive.created";
             "field.created": "field.created";
             "file.created": "file.created";
+            "node.agent_prompts_updated": "node.agent_prompts_updated";
             "node.metadata_updated": "node.metadata_updated";
             "node.purged": "node.purged";
+            "node.settings_updated": "node.settings_updated";
             "record.viewed": "record.viewed";
             "skill.created": "skill.created";
           }>;
@@ -5282,8 +5410,10 @@ declare const cloudContract: {
           "drive.created": "drive.created";
           "field.created": "field.created";
           "file.created": "file.created";
+          "node.agent_prompts_updated": "node.agent_prompts_updated";
           "node.metadata_updated": "node.metadata_updated";
           "node.purged": "node.purged";
+          "node.settings_updated": "node.settings_updated";
           "record.viewed": "record.viewed";
           "skill.created": "skill.created";
         }>;
@@ -6613,8 +6743,10 @@ declare const cloudContract: {
           "drive.created": "drive.created";
           "field.created": "field.created";
           "file.created": "file.created";
+          "node.agent_prompts_updated": "node.agent_prompts_updated";
           "node.metadata_updated": "node.metadata_updated";
           "node.purged": "node.purged";
+          "node.settings_updated": "node.settings_updated";
           "record.viewed": "record.viewed";
           "skill.created": "skill.created";
         }>;
@@ -6882,7 +7014,25 @@ declare const cloudContract: {
         role: z.ZodOptional<z.ZodNullable<z.ZodString>>;
       }, z.core.$strip>>>>;
       body: z.ZodString;
-      mentionsAi: z.ZodBoolean;
+      mentions: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodEnum<{
+          agent: "agent";
+          member: "member";
+        }>;
+        targetId: z.ZodString;
+        label: z.ZodString;
+        start: z.ZodNumber;
+        end: z.ZodNumber;
+        dispatchStatus: z.ZodEnum<{
+          failed: "failed";
+          linked: "linked";
+          not_applicable: "not_applicable";
+          queued: "queued";
+        }>;
+        sessionId: z.ZodNullable<z.ZodString>;
+        error: z.ZodNullable<z.ZodString>;
+      }, z.core.$strip>>>;
       createdAt: z.ZodString;
       updatedAt: z.ZodString;
     }, z.core.$strip>>, import("@orpc/contract").MergedErrorMap<Record<never, never>, Record<never, never>>, Record<never, never>>;
@@ -6896,7 +7046,15 @@ declare const cloudContract: {
       subjectId: z.ZodString;
       authorId: z.ZodDefault<z.ZodOptional<z.ZodString>>;
       body: z.ZodString;
-      mentionsAi: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+      mentions: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        type: z.ZodEnum<{
+          agent: "agent";
+          member: "member";
+        }>;
+        id: z.ZodString;
+        start: z.ZodNumber;
+        end: z.ZodNumber;
+      }, z.core.$strip>>>>;
     }, z.core.$strip>, z.ZodObject<{
       id: z.ZodString;
       subjectType: z.ZodEnum<{
@@ -6919,7 +7077,25 @@ declare const cloudContract: {
         role: z.ZodOptional<z.ZodNullable<z.ZodString>>;
       }, z.core.$strip>>>>;
       body: z.ZodString;
-      mentionsAi: z.ZodBoolean;
+      mentions: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodEnum<{
+          agent: "agent";
+          member: "member";
+        }>;
+        targetId: z.ZodString;
+        label: z.ZodString;
+        start: z.ZodNumber;
+        end: z.ZodNumber;
+        dispatchStatus: z.ZodEnum<{
+          failed: "failed";
+          linked: "linked";
+          not_applicable: "not_applicable";
+          queued: "queued";
+        }>;
+        sessionId: z.ZodNullable<z.ZodString>;
+        error: z.ZodNullable<z.ZodString>;
+      }, z.core.$strip>>>;
       createdAt: z.ZodString;
       updatedAt: z.ZodString;
     }, z.core.$strip>, import("@orpc/contract").MergedErrorMap<Record<never, never>, Record<never, never>>, Record<never, never>>;
@@ -7383,7 +7559,25 @@ declare const cloudContract: {
           role: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         }, z.core.$strip>>>>;
         body: z.ZodString;
-        mentionsAi: z.ZodBoolean;
+        mentions: z.ZodDefault<z.ZodArray<z.ZodObject<{
+          id: z.ZodString;
+          type: z.ZodEnum<{
+            agent: "agent";
+            member: "member";
+          }>;
+          targetId: z.ZodString;
+          label: z.ZodString;
+          start: z.ZodNumber;
+          end: z.ZodNumber;
+          dispatchStatus: z.ZodEnum<{
+            failed: "failed";
+            linked: "linked";
+            not_applicable: "not_applicable";
+            queued: "queued";
+          }>;
+          sessionId: z.ZodNullable<z.ZodString>;
+          error: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>>>;
         createdAt: z.ZodString;
         updatedAt: z.ZodString;
       }, z.core.$strip>>;
@@ -7391,7 +7585,7 @@ declare const cloudContract: {
   };
   live: {
     subscribe: import("@orpc/contract").ContractProcedure<import("@orpc/contract").Schema<unknown, unknown>, import("@orpc/contract").Schema<AsyncIteratorObject<{
-      kind: "change_request.created" | "change_request.deleted" | "change_request.merged" | "change_request.pending_review" | "change_request.reviewed" | "change_request.updated" | "node.metadata_updated";
+      kind: "change_request.created" | "change_request.deleted" | "change_request.merged" | "change_request.pending_review" | "change_request.reviewed" | "change_request.updated" | "node.metadata_updated" | "node.settings_updated";
       spaceId: string;
       actorId: string;
       changeRequestId: string | null;
@@ -7401,7 +7595,7 @@ declare const cloudContract: {
       viewIds: string[];
       operationCount: number;
     }, unknown, void>, AsyncIteratorClass<{
-      kind: "change_request.created" | "change_request.deleted" | "change_request.merged" | "change_request.pending_review" | "change_request.reviewed" | "change_request.updated" | "node.metadata_updated";
+      kind: "change_request.created" | "change_request.deleted" | "change_request.merged" | "change_request.pending_review" | "change_request.reviewed" | "change_request.updated" | "node.metadata_updated" | "node.settings_updated";
       spaceId: string;
       actorId: string;
       changeRequestId: string | null;
@@ -12444,10 +12638,10 @@ declare const cloudContract: {
       nodeId: z.ZodString;
       files: z.ZodRecord<z.ZodString, z.ZodString>;
       binaryFiles: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>>;
-      engine: z.ZodDefault<z.ZodEnum<{
+      engine: z.ZodEnum<{
         local: "local";
         remote: "remote";
-      }>>;
+      }>;
     }, z.core.$strip>, import("@orpc/contract").Schema<AsyncIteratorObject<{
       type: "log";
       line: string;
@@ -15156,8 +15350,17 @@ declare const cloudContract: {
       textContentHash: z.ZodNullable<z.ZodString>;
       byteCount: z.ZodNumber;
     }, z.core.$strip>, import("@orpc/contract").MergedErrorMap<Record<never, never>, Record<never, never>>, Record<never, never>>;
+    exportDocBodies: import("@orpc/contract").ContractProcedure<z.ZodObject<{
+      nodeIds: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+      bodies: z.ZodArray<z.ZodObject<{
+        nodeId: z.ZodString;
+        markdown: z.ZodString;
+      }, z.core.$strip>>;
+    }, z.core.$strip>, import("@orpc/contract").MergedErrorMap<Record<never, never>, Record<never, never>>, Record<never, never>>;
     importBegin: import("@orpc/contract").ContractProcedure<z.ZodObject<{
       sourceSpaceId: z.ZodString;
+      resume: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
     }, z.core.$strip>, z.ZodObject<{
       sessionId: z.ZodString;
     }, z.core.$strip>, import("@orpc/contract").MergedErrorMap<Record<never, never>, Record<never, never>>, Record<never, never>>;
@@ -19411,6 +19614,24 @@ declare const cloudContract: {
     listPage: import("@orpc/contract").ContractProcedure<z.ZodObject<{
       baseId: z.ZodString;
       viewId: z.ZodOptional<z.ZodString>;
+      filters: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        fieldSlug: z.ZodString;
+        fieldType: z.ZodOptional<z.ZodString>;
+        operator: z.ZodEnum<{
+          contains: "contains";
+          equals: "equals";
+          is_empty: "is_empty";
+          is_false: "is_false";
+          is_true: "is_true";
+          not_empty: "not_empty";
+        }>;
+        value: z.ZodOptional<z.ZodUnknown>;
+      }, z.core.$strip>>>;
+      dateRange: z.ZodOptional<z.ZodObject<{
+        fieldSlug: z.ZodString;
+        gte: z.ZodString;
+        lt: z.ZodString;
+      }, z.core.$strip>>;
       page: z.ZodDefault<z.ZodOptional<z.ZodCoercedNumber<unknown>>>;
       pageSize: z.ZodDefault<z.ZodOptional<z.ZodCoercedNumber<unknown>>>;
     }, z.core.$strip>, z.ZodObject<{
@@ -19637,6 +19858,39 @@ declare const cloudContract: {
     }, z.core.$strip>>>, z.ZodObject<{
       total: z.ZodNumber;
     }, z.core.$strip>, import("@orpc/contract").MergedErrorMap<Record<never, never>, Record<never, never>>, Record<never, never>>;
+    groupBy: import("@orpc/contract").ContractProcedure<z.ZodObject<{
+      baseId: z.ZodString;
+      fieldSlug: z.ZodString;
+      viewId: z.ZodOptional<z.ZodString>;
+      filters: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        fieldSlug: z.ZodString;
+        fieldType: z.ZodOptional<z.ZodString>;
+        operator: z.ZodEnum<{
+          contains: "contains";
+          equals: "equals";
+          is_empty: "is_empty";
+          is_false: "is_false";
+          is_true: "is_true";
+          not_empty: "not_empty";
+        }>;
+        value: z.ZodOptional<z.ZodUnknown>;
+      }, z.core.$strip>>>;
+    }, z.core.$strip>, z.ZodObject<{
+      groups: z.ZodArray<z.ZodObject<{
+        value: z.ZodNullable<z.ZodString>;
+        count: z.ZodNumber;
+      }, z.core.$strip>>;
+      total: z.ZodNumber;
+    }, z.core.$strip>, import("@orpc/contract").MergedErrorMap<Record<never, never>, import("@orpc/contract").MergedErrorMap<Record<never, never>, {
+      BAD_REQUEST: {
+        status: number;
+        message: string;
+      };
+      NOT_FOUND: {
+        status: number;
+        message: string;
+      };
+    }>>, Record<never, never>>;
     get: import("@orpc/contract").ContractProcedure<z.ZodUnion<readonly [z.ZodObject<{
       recordId: z.ZodString;
     }, z.core.$strict>, z.ZodObject<{
@@ -23731,8 +23985,10 @@ declare const activityItemSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
       "drive.created": "drive.created";
       "field.created": "field.created";
       "file.created": "file.created";
+      "node.agent_prompts_updated": "node.agent_prompts_updated";
       "node.metadata_updated": "node.metadata_updated";
       "node.purged": "node.purged";
+      "node.settings_updated": "node.settings_updated";
       "record.viewed": "record.viewed";
       "skill.created": "skill.created";
     }>;
@@ -24686,7 +24942,7 @@ type BusabaseSourceChannel = "web_ui" | "browser" | "openapi" | "sdk" | "cli" |
 type ReviewVerdict = "approved" | "rejected";
 type SearchResultKind = "record" | "change_request" | "base" | "file" | "node";
 type CommentSubjectType = "record" | "change_request" | "operation" | "commit";
-type AuditAction = "record.viewed" | "change_request.created" | "change_request.updated" | "change_request.deleted" | "change_request.reviewed" | "change_request.merged" | "base.created" | "field.created" | "doc.created" | "doc.updated" | "file.created" | "skill.created" | "drive.created" | "airapp.created" | "asset.deleted" | "asset.metadata_updated" | "asset.text_written" | "asset.text_marked_none" | "node.metadata_updated" | "node.purged";
+type AuditAction = "record.viewed" | "change_request.created" | "change_request.updated" | "change_request.deleted" | "change_request.reviewed" | "change_request.merged" | "base.created" | "field.created" | "doc.created" | "doc.updated" | "file.created" | "skill.created" | "drive.created" | "airapp.created" | "asset.deleted" | "asset.metadata_updated" | "asset.text_written" | "asset.text_marked_none" | "node.metadata_updated" | "node.settings_updated" | "node.agent_prompts_updated" | "node.purged";
 interface UserRefVO {
   id: string;
   name: string | null;
@@ -24731,6 +24987,19 @@ interface NodeVO {
   metadata: Record<string, unknown> & {
     version?: string;
   };
+  /**
+   * System settings the product DOES read and act on — the opposite of
+   * `metadata` above, which is why they are separate fields with separate
+   * endpoints. Written only by `PATCH /nodes/{nodeId}/settings`, whose input is
+   * a closed schema; the generic metadata endpoint cannot address it.
+   *
+   * Absent (or an absent key) means "unset". For an AirApp's engine that means
+   * "follow the app" — `airapp.json` decides — which is why absence has to stay
+   * distinguishable from any particular value.
+   */
+  settings?: {
+    airappEngine?: "browser" | "local" | "remote" | null;
+  };
   /**
    * This node's OWN declared visibility, or null when it inherits from its
    * ancestors. A real column rather than a metadata key, because it is the node
@@ -24867,6 +25136,34 @@ interface ReviewVO {
   visibleOperationHeads: Record<string, string>;
   createdAt: string;
 }
+type CommentMentionTargetType = "member" | "agent";
+/**
+ * Dispatch state of one mention BEFORE a session exists. Once `linked`, the
+ * agent session owns running/waiting/done/failed — it is never mirrored here.
+ */
+type CommentMentionDispatchStatus = "not_applicable" | "queued" | "linked" | "failed";
+/**
+ * One mention as the composer submits it. `start`/`end` are UTF-16 code unit
+ * offsets into the comment body (see the contract schema for why).
+ */
+interface CommentMentionInputDTO {
+  type: CommentMentionTargetType;
+  id: string;
+  start: number;
+  end: number;
+}
+interface CommentMentionVO {
+  id: string;
+  type: CommentMentionTargetType;
+  targetId: string;
+  /** Server-resolved display name; falls back to the raw target id. */
+  label: string;
+  start: number;
+  end: number;
+  dispatchStatus: CommentMentionDispatchStatus;
+  sessionId: string | null;
+  error: string | null;
+}
 interface CommentVO {
   id: string;
   subjectType: CommentSubjectType;
@@ -24878,7 +25175,7 @@ interface CommentVO {
   authorId: string;
   author?: UserRefVO | null;
   body: string;
-  mentionsAi: boolean;
+  mentions: CommentMentionVO[];
   createdAt: string;
   updatedAt: string;
 }
@@ -25026,4 +25323,4 @@ declare function resolveConfig(config?: BusabaseConfig): ResolvedConfig;
  */
 declare function createBusabaseClient(config?: BusabaseConfig): BusabaseClient;
 //#endregion
-export { FileTreeReadFileVO as $, SearchResultKind as A, AttachmentRef as At, VaultRuntimeEnv as B, NodeSearchResultVO as C, VIEW_FIELD_MIN_WIDTH as Ct, ReviewVO as D, ViewSortVO as Dt, OperationVO as E, ViewFilterVO as Et, VaultAccessPolicy as F, CREATABLE_NODE_TYPES as Ft, AssetDetailVO as G, VaultSettingsVO as H, VaultEnvironment as I, CreatableNodeType as It, AssetVO as J, AssetTextStatus as K, VaultItemInput as L, NodeType as Lt, SourceAttributionVO as M, cloudContract as Mt, UserRefVO as N, NodeIcon as Nt, ReviewVerdict as O, ViewType as Ot, UpdateVaultSettingsDTO as P, NodeIconSchema as Pt, FileTreeNodeVO as Q, VaultItemKind as R, OperationKind as Rt, LookupRollup as S, VIEW_FIELD_MAX_WIDTH as St, OperationStatus as T, ViewFilterOperator as Tt, FileNodeMetadata as U, VaultScopeType as V, FileNodeVO as W, GrepResultVO as X, GrepInputDTO as Y, FileTreeFileVO as Z, ChangeRequestVO as _, GalleryCardSize as _t, createBusabaseClient as a, FormPageSourceVO as at, CommitVO as b, RecordLinkVO as bt, AuditAction as c, FormThemeVO as ct, ChangeRequestBatchFailureVO as d, ListFormsVO as dt, NodeDetailVO as et, ChangeRequestCountsVO as f, SubmitFormDTO as ft, ChangeRequestTargetType as g, BaseVO as gt, ChangeRequestStatus as h, BaseFieldVO as ht, ResolvedConfig as i, FormFieldBindingVO as it, SearchResultVO as j, CloudContract as jt, SearchResponseVO as k, ViewVO as kt, AuditEventVO as l, FormVO as lt, ChangeRequestReviewBatchResultVO as m, AssetAttachmentRef as mt, BusabaseConfig as n, CreateFormDTO as nt, resolveConfig as o, FormShareVO as ot, ChangeRequestMergeBatchResultVO as p, UpdateFormDTO as pt, AssetUsageVO as q, DEFAULT_BASE_URL as r, FormBoundFieldVO as rt, AgentTaskVO as s, FormSubmitResultVO as st, BusabaseClient as t, ActivityItemVO as tt, BusabaseSourceChannel as u, ListFormsDTO as ut, CommentSubjectType as v, GalleryCoverFit as vt, NodeVO as w, ViewConfigVO as wt, FieldType as x, RecordVO as xt, CommentVO as y, GanttScale as yt, VaultItemVO as z };
+export { GrepInputDTO as $, OperationVO as A, ViewFilterVO as At, VaultEnvironment as B, CreatableNodeType as Bt, CommentVO as C, GanttScale as Ct, NodeSearchResultVO as D, VIEW_FIELD_MIN_WIDTH as Dt, LookupRollup as E, VIEW_FIELD_MAX_WIDTH as Et, SearchResultVO as F, CloudContract as Ft, VaultScopeType as G, VaultItemKind as H, OperationKind as Ht, SourceAttributionVO as I, cloudContract as It, FileNodeVO as J, VaultSettingsVO as K, UserRefVO as L, NodeIcon as Lt, ReviewVerdict as M, ViewType as Mt, SearchResponseVO as N, ViewVO as Nt, NodeVO as O, ViewConfigVO as Ot, SearchResultKind as P, AttachmentRef as Pt, AssetVO as Q, UpdateVaultSettingsDTO as R, NodeIconSchema as Rt, CommentSubjectType as S, GalleryCoverFit as St, FieldType as T, RecordVO as Tt, VaultItemVO as U, VaultItemInput as V, NodeType as Vt, VaultRuntimeEnv as W, AssetTextStatus as X, AssetDetailVO as Y, AssetUsageVO as Z, ChangeRequestVO as _, UpdateFormDTO as _t, createBusabaseClient as a, ActivityItemVO as at, CommentMentionTargetType as b, BaseVO as bt, AuditAction as c, FormFieldBindingVO as ct, ChangeRequestBatchFailureVO as d, FormSubmitResultVO as dt, GrepResultVO as et, ChangeRequestCountsVO as f, FormThemeVO as ft, ChangeRequestTargetType as g, SubmitFormDTO as gt, ChangeRequestStatus as h, ListFormsVO as ht, ResolvedConfig as i, NodeDetailVO as it, ReviewVO as j, ViewSortVO as jt, OperationStatus as k, ViewFilterOperator as kt, AuditEventVO as l, FormPageSourceVO as lt, ChangeRequestReviewBatchResultVO as m, ListFormsDTO as mt, BusabaseConfig as n, FileTreeNodeVO as nt, resolveConfig as o, CreateFormDTO as ot, ChangeRequestMergeBatchResultVO as p, FormVO as pt, FileNodeMetadata as q, DEFAULT_BASE_URL as r, FileTreeReadFileVO as rt, AgentTaskVO as s, FormBoundFieldVO as st, BusabaseClient as t, FileTreeFileVO as tt, BusabaseSourceChannel as u, FormShareVO as ut, CommentMentionDispatchStatus as v, AssetAttachmentRef as vt, CommitVO as w, RecordLinkVO as wt, CommentMentionVO as x, GalleryCardSize as xt, CommentMentionInputDTO as y, BaseFieldVO as yt, VaultAccessPolicy as z, CREATABLE_NODE_TYPES as zt };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { $ as FileTreeReadFileVO, A as SearchResultKind, At as AttachmentRef, B as VaultRuntimeEnv, C as NodeSearchResultVO, Ct as VIEW_FIELD_MIN_WIDTH, D as ReviewVO, Dt as ViewSortVO, E as OperationVO, Et as ViewFilterVO, F as VaultAccessPolicy, Ft as CREATABLE_NODE_TYPES, G as AssetDetailVO, H as VaultSettingsVO, I as VaultEnvironment, It as CreatableNodeType, J as AssetVO, K as AssetTextStatus, L as VaultItemInput, Lt as NodeType, M as SourceAttributionVO, Mt as cloudContract, N as UserRefVO, Nt as NodeIcon, O as ReviewVerdict, Ot as ViewType, P as UpdateVaultSettingsDTO, Pt as NodeIconSchema, Q as FileTreeNodeVO, R as VaultItemKind, Rt as OperationKind, S as LookupRollup, St as VIEW_FIELD_MAX_WIDTH, T as OperationStatus, Tt as ViewFilterOperator, U as FileNodeMetadata, V as VaultScopeType, W as FileNodeVO, X as GrepResultVO, Y as GrepInputDTO, Z as FileTreeFileVO, _ as ChangeRequestVO, _t as GalleryCardSize, a as createBusabaseClient, at as FormPageSourceVO, b as CommitVO, bt as RecordLinkVO, c as AuditAction, ct as FormThemeVO, d as ChangeRequestBatchFailureVO, dt as ListFormsVO, et as NodeDetailVO, f as ChangeRequestCountsVO, ft as SubmitFormDTO, g as ChangeRequestTargetType, gt as BaseVO, h as ChangeRequestStatus, ht as BaseFieldVO, i as ResolvedConfig, it as FormFieldBindingVO, j as SearchResultVO, jt as CloudContract, k as SearchResponseVO, kt as ViewVO, l as AuditEventVO, lt as FormVO, m as ChangeRequestReviewBatchResultVO, mt as AssetAttachmentRef, n as BusabaseConfig, nt as CreateFormDTO, o as resolveConfig, ot as FormShareVO, p as ChangeRequestMergeBatchResultVO, pt as UpdateFormDTO, q as AssetUsageVO, r as DEFAULT_BASE_URL, rt as FormBoundFieldVO, s as AgentTaskVO, st as FormSubmitResultVO, t as BusabaseClient, tt as ActivityItemVO, u as BusabaseSourceChannel, ut as ListFormsDTO, v as CommentSubjectType, vt as GalleryCoverFit, w as NodeVO, wt as ViewConfigVO, x as FieldType, xt as RecordVO, y as CommentVO, yt as GanttScale, z as VaultItemVO } from "./client-DJmL8Jl_.js";
+import { $ as GrepInputDTO, A as OperationVO, At as ViewFilterVO, B as VaultEnvironment, Bt as CreatableNodeType, C as CommentVO, Ct as GanttScale, D as NodeSearchResultVO, Dt as VIEW_FIELD_MIN_WIDTH, E as LookupRollup, Et as VIEW_FIELD_MAX_WIDTH, F as SearchResultVO, Ft as CloudContract, G as VaultScopeType, H as VaultItemKind, Ht as OperationKind, I as SourceAttributionVO, It as cloudContract, J as FileNodeVO, K as VaultSettingsVO, L as UserRefVO, Lt as NodeIcon, M as ReviewVerdict, Mt as ViewType, N as SearchResponseVO, Nt as ViewVO, O as NodeVO, Ot as ViewConfigVO, P as SearchResultKind, Pt as AttachmentRef, Q as AssetVO, R as UpdateVaultSettingsDTO, Rt as NodeIconSchema, S as CommentSubjectType, St as GalleryCoverFit, T as FieldType, Tt as RecordVO, U as VaultItemVO, V as VaultItemInput, Vt as NodeType, W as VaultRuntimeEnv, X as AssetTextStatus, Y as AssetDetailVO, Z as AssetUsageVO, _ as ChangeRequestVO, _t as UpdateFormDTO, a as createBusabaseClient, at as ActivityItemVO, b as CommentMentionTargetType, bt as BaseVO, c as AuditAction, ct as FormFieldBindingVO, d as ChangeRequestBatchFailureVO, dt as FormSubmitResultVO, et as GrepResultVO, f as ChangeRequestCountsVO, ft as FormThemeVO, g as ChangeRequestTargetType, gt as SubmitFormDTO, h as ChangeRequestStatus, ht as ListFormsVO, i as ResolvedConfig, it as NodeDetailVO, j as ReviewVO, jt as ViewSortVO, k as OperationStatus, kt as ViewFilterOperator, l as AuditEventVO, lt as FormPageSourceVO, m as ChangeRequestReviewBatchResultVO, mt as ListFormsDTO, n as BusabaseConfig, nt as FileTreeNodeVO, o as resolveConfig, ot as CreateFormDTO, p as ChangeRequestMergeBatchResultVO, pt as FormVO, q as FileNodeMetadata, r as DEFAULT_BASE_URL, rt as FileTreeReadFileVO, s as AgentTaskVO, st as FormBoundFieldVO, t as BusabaseClient, tt as FileTreeFileVO, u as BusabaseSourceChannel, ut as FormShareVO, v as CommentMentionDispatchStatus, vt as AssetAttachmentRef, w as CommitVO, wt as RecordLinkVO, x as CommentMentionVO, xt as GalleryCardSize, y as CommentMentionInputDTO, yt as BaseFieldVO, z as VaultAccessPolicy, zt as CREATABLE_NODE_TYPES } from "./client-DbETz_5k.js";
 import { z } from "zod";
 //#region src/url.d.ts
 /**
@@ -426,4 +426,4 @@ declare class Busabase {
   }>>>>;
 }
 //#endregion
-export { type ActivityItemVO, type AgentTaskVO, type FileTreeFileVO as AirAppFileVO, type FileTreeFileVO as DriveFileVO, type FileTreeFileVO, type FileTreeFileVO as SkillFileVO, type FileTreeReadFileVO as AirAppReadFileVO, type FileTreeReadFileVO as DriveReadFileVO, type FileTreeReadFileVO, type FileTreeReadFileVO as SkillReadFileVO, type FileTreeNodeVO as AirAppVO, type FileTreeNodeVO as DriveVO, type FileTreeNodeVO, type FileTreeNodeVO as SkillVO, type AssetAttachmentRef, type AssetDetailVO, type AssetTextStatus, type AssetUsageVO, type AssetVO, type AttachmentRef, type AuditAction, type AuditEventVO, type BaseFieldVO, type BaseVO, Busabase, type BusabaseAssetsClient, BusabaseChangeRequestsClient, type BusabaseClient, type BusabaseConfig, type BusabaseRecordsClient, type BusabaseSourceChannel, CREATABLE_NODE_TYPES, type ChangeRequestBatchFailureVO, type ChangeRequestCountsVO, type ChangeRequestMergeBatchResultVO, type ChangeRequestReviewBatchResultVO, type ChangeRequestStatus, type ChangeRequestTargetType, type ChangeRequestVO, type CloudContract, type CommentSubjectType, type CommentVO, type CommitVO, type CreatableNodeType, type CreateFormDTO, DEFAULT_BASE_URL, type FieldType, type FileNodeMetadata, type FileNodeVO, type FormBoundFieldVO, type FormFieldBindingVO, type FormPageSourceVO, type FormShareVO, type FormSubmitResultVO, type FormThemeVO, type FormVO, type GalleryCardSize, type GalleryCoverFit, type GanttScale, type ListFormsDTO, type ListFormsVO, type LookupRollup, type NodeDetailVO, type NodeIcon, type NodeIconSchema, type NodeSearchResultVO, type NodeType, type NodeVO, type NodeWebUrlInput, type OperationKind, type OperationStatus, type OperationVO, type RecordByFieldInput, type RecordLinkVO, type RecordVO, type ResolvedConfig, type ReviewVO, type ReviewVerdict, type SearchResponseVO, type SearchResultKind, type SearchResultVO, type SourceAttributionVO, type SubmitFormDTO, type UpdateFormDTO, type UpdateVaultSettingsDTO, type UserRefVO, type VIEW_FIELD_MAX_WIDTH, type VIEW_FIELD_MIN_WIDTH, type VaultAccessPolicy, type VaultEnvironment, type VaultItemInput, type VaultItemKind, type VaultItemVO, type VaultRuntimeEnv, type VaultScopeType, type VaultSettingsVO, type ViewConfigVO, type ViewFilterOperator, type ViewFilterVO, type ViewSortVO, type ViewType, type ViewVO, cloudContract, createBusabaseClient, getRecordByField, grepAssets, nodeWebUrl, normalizeBaseUrl, resolveConfig, toFilesOnlyGrepResult, toUnifiedFilesGrepInput };
+export { type ActivityItemVO, type AgentTaskVO, type FileTreeFileVO as AirAppFileVO, type FileTreeFileVO as DriveFileVO, type FileTreeFileVO, type FileTreeFileVO as SkillFileVO, type FileTreeReadFileVO as AirAppReadFileVO, type FileTreeReadFileVO as DriveReadFileVO, type FileTreeReadFileVO, type FileTreeReadFileVO as SkillReadFileVO, type FileTreeNodeVO as AirAppVO, type FileTreeNodeVO as DriveVO, type FileTreeNodeVO, type FileTreeNodeVO as SkillVO, type AssetAttachmentRef, type AssetDetailVO, type AssetTextStatus, type AssetUsageVO, type AssetVO, type AttachmentRef, type AuditAction, type AuditEventVO, type BaseFieldVO, type BaseVO, Busabase, type BusabaseAssetsClient, BusabaseChangeRequestsClient, type BusabaseClient, type BusabaseConfig, type BusabaseRecordsClient, type BusabaseSourceChannel, CREATABLE_NODE_TYPES, type ChangeRequestBatchFailureVO, type ChangeRequestCountsVO, type ChangeRequestMergeBatchResultVO, type ChangeRequestReviewBatchResultVO, type ChangeRequestStatus, type ChangeRequestTargetType, type ChangeRequestVO, type CloudContract, type CommentMentionDispatchStatus, type CommentMentionInputDTO, type CommentMentionTargetType, type CommentMentionVO, type CommentSubjectType, type CommentVO, type CommitVO, type CreatableNodeType, type CreateFormDTO, DEFAULT_BASE_URL, type FieldType, type FileNodeMetadata, type FileNodeVO, type FormBoundFieldVO, type FormFieldBindingVO, type FormPageSourceVO, type FormShareVO, type FormSubmitResultVO, type FormThemeVO, type FormVO, type GalleryCardSize, type GalleryCoverFit, type GanttScale, type ListFormsDTO, type ListFormsVO, type LookupRollup, type NodeDetailVO, type NodeIcon, type NodeIconSchema, type NodeSearchResultVO, type NodeType, type NodeVO, type NodeWebUrlInput, type OperationKind, type OperationStatus, type OperationVO, type RecordByFieldInput, type RecordLinkVO, type RecordVO, type ResolvedConfig, type ReviewVO, type ReviewVerdict, type SearchResponseVO, type SearchResultKind, type SearchResultVO, type SourceAttributionVO, type SubmitFormDTO, type UpdateFormDTO, type UpdateVaultSettingsDTO, type UserRefVO, type VIEW_FIELD_MAX_WIDTH, type VIEW_FIELD_MIN_WIDTH, type VaultAccessPolicy, type VaultEnvironment, type VaultItemInput, type VaultItemKind, type VaultItemVO, type VaultRuntimeEnv, type VaultScopeType, type VaultSettingsVO, type ViewConfigVO, type ViewFilterOperator, type ViewFilterVO, type ViewSortVO, type ViewType, type ViewVO, cloudContract, createBusabaseClient, getRecordByField, grepAssets, nodeWebUrl, normalizeBaseUrl, resolveConfig, toFilesOnlyGrepResult, toUnifiedFilesGrepInput };

package/dist/index.js

@@ -354,7 +354,7 @@ const LocaleSchema = z.enum({
 * - ZH: isIString 接受 JSON 字符串并尝试解析为按语言分布的对象；纯字符串将返回 false。
 */
 const iStringRecordSchema = z.partialRecord(LocaleSchema, z.string());
-z.union([z.string(), iStringRecordSchema]).describe("i18n string");
+const iStringSchema = z.union([z.string(), iStringRecordSchema]).describe("i18n string");
 //#endregion
 //#region ../../packages/busabase-contract/src/contract/auto-merge.ts
 /**
@@ -1082,6 +1082,81 @@ const NodeIconSchema = z.discriminatedUnion("type", [z.object({
 	}).optional()
 })]);
 //#endregion
+//#region ../../packages/busabase-contract/src/contract/node-agent-prompt-schemas.ts
+/**
+* Per-node custom scenario prompts (`node.metadata.agentPrompts`) — the single
+* schema shared by BOTH write and read paths, per
+* `apps/busabase-cloud/content/spec/node-agent-prompts-v2.md` §7.3:
+*
+* - Write: `busabase-cli nodes set-agent-prompts` validates a file against this
+*   schema client-side, before calling `nodes.updateMetadata` — a malformed file
+*   never reaches the network.
+* - Read: `buildNodeAgentPrompts` (`packages/busabase-core/.../node-agent-prompts.ts`)
+*   `.safeParse`s whatever is stored in `metadata.agentPrompts` and falls back to
+*   the node type's default scenarios on failure, so a bad write (or a manual
+*   jsonb edit) can never crash the Agent Prompts dialog.
+*
+* One schema, one place to edit the limits — do not duplicate this validation on
+* either side.
+*/
+/** Recommended limits from the spec (§7.3) — kept as named constants so a limit
+* change has exactly one place to edit, and so error messages can cite them. */
+const CUSTOM_AGENT_PROMPT_LIMITS = {
+	/** Max custom prompts per node. */
+	maxPrompts: 50,
+	/** Max characters per localized `label` value. */
+	maxLabelChars: 80,
+	/** Max bytes (UTF-8) per localized `body` value. */
+	maxBodyBytes: 8192
+};
+/** Same intent vocabulary `PromptDef.intent` uses — `change` is the router-side
+* default when omitted, matching the existing curated-prompt behavior. */
+const customPromptIntentSchema = z.enum(["read-only", "change"]);
+const iStringLocaleValues = (value) => typeof value === "string" ? [value] : Object.values(value);
+/** UTF-8 byte length — `body` includes CJK/JA text, whose per-character byte
+* cost is not 1, so a character-count limit alone would under-enforce §7.3's
+* "8 KiB per localized body" budget. */
+const utf8ByteLength = (value) => new TextEncoder().encode(value).length;
+const customPromptLabelSchema = iStringSchema.refine((value) => iStringLocaleValues(value).every((v) => v.length <= CUSTOM_AGENT_PROMPT_LIMITS.maxLabelChars), { message: `label must be at most ${CUSTOM_AGENT_PROMPT_LIMITS.maxLabelChars} characters per locale` });
+const customPromptBodySchema = iStringSchema.refine((value) => iStringLocaleValues(value).every((v) => utf8ByteLength(v) <= CUSTOM_AGENT_PROMPT_LIMITS.maxBodyBytes), { message: `body must be at most ${CUSTOM_AGENT_PROMPT_LIMITS.maxBodyBytes} bytes (UTF-8) per locale` });
+/**
+* One custom scenario prompt. `body`'s `{target}` placeholder is substituted at
+* render time with the same target string `PromptDef.body(target)` receives
+* today (see `node-agent-prompts.ts`) — this schema does not interpolate it.
+*/
+const customPromptDefSchema = z.object({
+	/** Stable id, unique within this node's custom list. */
+	key: z.string().trim().min(1, { message: "key must not be empty" }),
+	/** Defaults to `change` (same default the curated prompts use) so a prompt
+	* cannot silently bypass the approval-first policy by omission. */
+	intent: customPromptIntentSchema.optional(),
+	/** Short title shown in the dialog's left list. */
+	label: customPromptLabelSchema,
+	/** Template text; "{target}" is substituted with the rendered target line. */
+	body: customPromptBodySchema
+});
+/**
+* The full `metadata.agentPrompts` array. `.max` bounds the list; the
+* `superRefine` catches duplicate keys with an issue path pointing at the
+* offending entry, so a CLI/server validation error names which entry and
+* which key collided instead of a bare "keys must be unique".
+*/
+const customAgentPromptsSchema = z.array(customPromptDefSchema).max(CUSTOM_AGENT_PROMPT_LIMITS.maxPrompts, { message: `at most ${CUSTOM_AGENT_PROMPT_LIMITS.maxPrompts} custom prompts per node` }).superRefine((prompts, ctx) => {
+	const firstIndexByKey = /* @__PURE__ */ new Map();
+	prompts.forEach((prompt, index) => {
+		const firstIndex = firstIndexByKey.get(prompt.key);
+		if (firstIndex === void 0) {
+			firstIndexByKey.set(prompt.key, index);
+			return;
+		}
+		ctx.addIssue({
+			code: "custom",
+			path: [index, "key"],
+			message: `duplicate key "${prompt.key}" — already used at entry ${firstIndex + 1}`
+		});
+	});
+});
+//#endregion
 //#region ../../packages/busabase-contract/src/contract/schemas.ts
 const nodeSchema = z.lazy(() => z.object({
 	id: z.string(),
@@ -1091,6 +1166,7 @@ const nodeSchema = z.lazy(() => z.object({
 	name: z.string(),
 	description: z.string(),
 	metadata: z.object({ version: z.string().optional() }).catchall(z.unknown()).default({}),
+	settings: nodeSettingsSchema.default({}),
 	explicitVisibility: z.enum([
 		"private",
 		"workspace",
@@ -1174,6 +1250,65 @@ const updateNodeMetadataInputSchema = z.object({
 	nodeId: z.string(),
 	metadata: z.record(z.string(), z.unknown())
 });
+/**
+* System settings Busabase itself acts on, per node.
+*
+* A CLOSED object, unlike `metadata`'s `z.record(z.string(), z.unknown())`.
+* That difference is the point: `metadata` is the open bag callers put their
+* own keys in, and its endpoint merges whatever it is handed. Anything the
+* product *reads and acts on* must not live there — `metadata.visibility` had
+* to be pulled out into its own column precisely because the generic endpoint
+* handed a `write`-level actor a door into an ACL input.
+*
+* Adding a key here is a deliberate change to this schema, which is what keeps
+* `PATCH /nodes/{nodeId}/settings` from becoming a second free-form bag.
+*
+* `strictObject`, not `object`: zod's default is to STRIP an unknown key, which
+* would hand a client that misspelled `airappEngine` a 200 and no effect —
+* exactly the silent failure a closed schema exists to prevent. Verified
+* against a running server, where the permissive version returned 200.
+*/
+const nodeSettingsSchema = z.strictObject({ 
+/**
+* Which engine an AirApp runs on, when a human has chosen.
+*
+* `undefined` means "follow the app" — `airapp.json`'s `preferredEngine`
+* decides, or the default does. A value means somebody overrode it in the
+* node settings dialog, and it outranks the manifest from then on. So absence
+* must stay distinguishable from any particular value; `null` clears an
+* override and returns the node to following the app.
+*/
+airappEngine: z.enum([
+	"browser",
+	"local",
+	"remote"
+]).nullish() });
+const updateNodeSettingsInputSchema = z.object({
+	nodeId: z.string(),
+	settings: nodeSettingsSchema
+});
+/**
+* This node's custom scenario prompts.
+*
+* A separate read from `nodes.get`/`nodes.list` on purpose: the list is capped
+* at 50 prompts x 8 KiB of body per locale, so carrying it on every node of
+* every sidebar load is exactly what its own column exists to avoid. The dialog
+* asks for it when it opens.
+*
+* `agentPrompts: null` means "this node has never set any" — distinct from `[]`,
+* which means "set, and deliberately empty". Both fall back to the node type's
+* default scenarios in the UI, but only the first is a node nobody has touched.
+*/
+const getNodeAgentPromptsInputSchema = z.object({ nodeId: z.string() });
+const nodeAgentPromptsSchema = z.object({
+	nodeId: z.string(),
+	agentPrompts: customAgentPromptsSchema.nullable()
+});
+const updateNodeAgentPromptsInputSchema = z.object({
+	nodeId: z.string(),
+	/** Replaces the whole list — this is not a merge. Send `null` to clear. */
+	agentPrompts: customAgentPromptsSchema.nullable()
+});
 const searchNodesByNameInputSchema = z.object({
 	query: z.string().min(1),
 	limit: z.coerce.number().int().min(1).max(50).optional().default(20)
@@ -1269,6 +1404,55 @@ const commentSubjectTypeSchema = z.enum([
 	"operation",
 	"commit"
 ]);
+/**
+* Who a mention points at. `member` tags a person; `agent` names a launchable
+* Agent target and is what actually starts a session.
+*/
+const commentMentionTargetTypeSchema = z.enum(["member", "agent"]);
+/**
+* Dispatch lifecycle of ONE mention row, before a session exists.
+*
+* `not_applicable` is every member row (a person is not dispatched to).
+* Once `linked`, running/waiting/done/failed belongs to the agent session,
+* never to a second status column here.
+*/
+const commentMentionDispatchStatusSchema = z.enum([
+	"not_applicable",
+	"queued",
+	"linked",
+	"failed"
+]);
+/**
+* One mention as the composer submits it.
+*
+* `start`/`end` are **UTF-16 code unit** offsets into `body` — the same unit
+* `<textarea>` selection APIs and `String.prototype.slice` use, so nothing has
+* to convert at the UI boundary. A label containing an astral-plane character
+* (an emoji in a display name) therefore spans two units per visible glyph;
+* the server rejects a span that would split a surrogate pair.
+*
+* No `label` here on purpose: the client never supplies identity. The server
+* resolves the display name from the member/catalog it already trusts.
+*/
+const commentMentionInputSchema = z.object({
+	type: commentMentionTargetTypeSchema,
+	/** Member/actor id, or launchable agent slug (`claude-acp`, `buda:<agentId>`). */
+	id: z.string().min(1),
+	start: z.number().int().min(0),
+	end: z.number().int().min(0)
+});
+const commentMentionSchema = z.object({
+	id: z.string(),
+	type: commentMentionTargetTypeSchema,
+	targetId: z.string(),
+	/** Server-resolved display name. Falls back to the raw target id. */
+	label: z.string(),
+	start: z.number().int(),
+	end: z.number().int(),
+	dispatchStatus: commentMentionDispatchStatusSchema,
+	sessionId: z.string().nullable(),
+	error: z.string().nullable()
+});
 const commentSchema = z.object({
 	id: z.string(),
 	subjectType: commentSubjectTypeSchema,
@@ -1280,7 +1464,7 @@ const commentSchema = z.object({
 	authorId: z.string(),
 	author: userRefSchema.nullable().optional().default(null),
 	body: z.string(),
-	mentionsAi: z.boolean(),
+	mentions: z.array(commentMentionSchema).default([]),
 	createdAt: z.string(),
 	updatedAt: z.string()
 });
@@ -1369,7 +1553,8 @@ const liveEventSchema = z.object({
 		"change_request.reviewed",
 		"change_request.merged",
 		"change_request.pending_review",
-		"node.metadata_updated"
+		"node.metadata_updated",
+		"node.settings_updated"
 	]),
 	spaceId: z.string(),
 	actorId: z.string(),
@@ -1400,6 +1585,8 @@ const auditActionSchema = z.enum([
 	"asset.text_written",
 	"asset.text_marked_none",
 	"node.metadata_updated",
+	"node.settings_updated",
+	"node.agent_prompts_updated",
 	"node.purged"
 ]);
 const auditEventSchema = z.object({
@@ -1515,7 +1702,12 @@ const commentSubjectInputSchema = z.object({
 const createCommentInputSchema = commentSubjectInputSchema.extend({
 	authorId: z.string().optional().default("local-admin"),
 	body: z.string().trim().min(1),
-	mentionsAi: z.boolean().optional().default(false)
+	/**
+	* Structured mentions, owned by the composer. Never inferred from the body by
+	* regex: display names contain spaces and collide with ordinary prose, so
+	* "ask codex about this" must not invoke Codex.
+	*/
+	mentions: z.array(commentMentionInputSchema).optional().default([])
 });
 const listInputSchema = z.object({ limit: z.coerce.number().int().min(1).max(100).optional().default(50) }).optional().default({ limit: 50 });
 /**
@@ -1818,8 +2010,14 @@ const airAppRunLocalInputSchema = z.object({
 	/** Where the server should run it. `"local"` spawns a bare process on the
 	*  Busabase host (previewable, data bridge via reverse proxy, NOT isolated);
 	*  `"remote"` runs the same lifecycle on a provisioned machine elsewhere.
-	*  `"browser"` never reaches this endpoint — it runs entirely in the tab. */
-	engine: z.enum(["local", "remote"]).default("local")
+	*  `"browser"` never reaches this endpoint — it runs entirely in the tab.
+	*
+	*  Required, deliberately. This used to default to `"local"`, so a call that
+	*  simply omitted the field asked the server to spawn a host process — the
+	*  most privileged of the two options, reached by saying nothing. Naming the
+	*  engine is now the caller's job, and the handler independently refuses one
+	*  this deployment does not offer. */
+	engine: z.enum(["local", "remote"])
 });
 const airAppRuntimeEventSchema = z.discriminatedUnion("type", [
 	z.object({
@@ -2410,6 +2608,41 @@ const listRecordsResponseSchema = z.object({
 const listRecordsPageInputSchema = z.object({
 	baseId: z.string().min(1),
 	viewId: z.string().min(1).optional(),
+	/**
+	* Extra conditions ANDed with the View's own filters — "this View, further
+	* narrowed". The motivating case is one board column: the saved View's
+	* filters plus `stackField equals <choice>`, paged independently of the
+	* other columns.
+	*
+	* Unlike `records.list`'s `filters` (a SUPERSET push-down the client then
+	* narrows), these are applied with the same authority as a saved View's:
+	* every returned page is exactly what the client's own matcher would keep.
+	* That distinction is the whole point — a *superset* page can be missing
+	* records, and a board column that silently drops cards reads as data loss.
+	*/
+	filters: z.array(listRecordsFilterSchema).optional(),
+	/**
+	* Scope the page to records whose `date`/`created_time`/`updated_time` field
+	* falls in `[gte, lt)` — an absolute UTC instant range, not a `filters`
+	* condition. It is deliberately NOT an operator on `listRecordsFilterSchema`:
+	* that model mirrors the client's label-based view-filter matching (see
+	* `recordMatchesViewFilter`), which for a date renders via
+	* `toLocaleDateString()` — meaningless without knowing the viewer's
+	* timezone, which the server never has. A UTC instant range has no such
+	* ambiguity, so it is resolved once here, by the caller (who DOES know the
+	* viewer's timezone), and applied as a real timestamp comparison.
+	*
+	* The motivating case is a Calendar month grid: the client computes the UTC
+	* bounds of its own local 42-day grid and asks for only that slice, instead
+	* of every record in the Base.
+	*/
+	dateRange: z.object({
+		fieldSlug: z.string().min(1),
+		/** Inclusive lower bound, ISO 8601 UTC instant. */
+		gte: z.string(),
+		/** Exclusive upper bound, ISO 8601 UTC instant. */
+		lt: z.string()
+	}).optional(),
 	page: z.coerce.number().int().min(1).optional().default(1),
 	pageSize: z.coerce.number().int().min(1).max(100).optional().default(50)
 });
@@ -2454,6 +2687,42 @@ const countRecordsInputSchema = z.object({
 const countRecordsResponseSchema = z.object({ 
 /** Total active records in the space (optionally scoped to a base). */
 total: z.number().int().nonnegative() });
+const groupRecordsInputSchema = z.object({
+	/** Group within exactly one Base — a field slug is only unambiguous there. */
+	baseId: z.string().min(1),
+	/**
+	* The field to group by. Restricted to `select` and `checkbox`: their stored
+	* value IS the grouping key (a choice id / a boolean), so a SQL GROUP BY
+	* returns exactly the buckets a client would build. Text/number keys would
+	* be truncated at the projection limit, and date keys would bucket by the
+	* server's timezone rather than the viewer's — both would report a
+	* confidently wrong split, so they're rejected instead of approximated.
+	*/
+	fieldSlug: z.string().min(1),
+	/** Group only the rows a saved View would display (its filters; sort ignored). */
+	viewId: z.string().min(1).optional(),
+	/** Ad-hoc filters, ANDed with the View's own when both are given. */
+	filters: z.array(listRecordsFilterSchema).optional()
+});
+const groupRecordsResponseSchema = z.object({
+	groups: z.array(z.object({
+		/**
+		* The raw stored key: a `select` choice id, or `"true"`/`"false"` for a
+		* checkbox. For a select, `null` is the bucket of records with no value
+		* (what a Kanban board shows as its "Uncategorized" column). A checkbox
+		* never reports `null` — an unset checkbox counts as `"false"`, matching
+		* how view filters already treat it (`is_false` covers null/undefined).
+		*
+		* Choice LABELS are deliberately not resolved here — the client already
+		* holds the Base's field definitions and renders labels itself, and
+		* returning ids keeps this response stable across a choice rename.
+		*/
+		value: z.string().nullable(),
+		count: z.number().int().nonnegative()
+	})),
+	/** Sum of every group's count — the same number `records.count` would return. */
+	total: z.number().int().nonnegative()
+});
 const createChangeRequestInputSchema = z.object({
 	fields: z.record(z.string(), z.unknown()).describe("Record field values keyed by field slug. The base's PRIMARY field (its first field) becomes the record's display name and the change request title everywhere — always give it a short, human-readable value, never an id or placeholder."),
 	message: z.string().optional().default("Initial change request").describe("Explanation shown to the human reviewer. Write a conventional-commit style subject — imperative verb + what + why, e.g. \"Add Acme Corp — qualified lead from the June webinar\"."),
@@ -2653,7 +2922,7 @@ const recordContract = {
 		path: "/records/page",
 		tags: ["Records"],
 		summary: "List a numbered record page",
-		successDescription: "A random-access page of active records. When viewId is supplied, the saved view is authoritatively filtered and sorted before total and page slicing are calculated."
+		successDescription: "A random-access page of active records. When viewId is supplied, the saved view is authoritatively filtered and sorted before total and page slicing are calculated. `dateRange` additionally scopes to a `[gte, lt)` UTC instant window on a date/created_time/updated_time field."
 	}).input(listRecordsPageInputSchema).output(listRecordsPageResponseSchema),
 	count: oc.route({
 		method: "GET",
@@ -2663,6 +2932,23 @@ const recordContract = {
 		description: "A real SQL COUNT — always the exact total, never a partial or capped number, so it's safe to render as a canonical figure (e.g. a dashboard summary tile). Plain `baseId` scoping is always cheap. Adding `viewId` and/or `filters` is exact too — provably-exact conditions (e.g. text equals/contains, not_empty/is_empty, checkbox is_true/is_false) stay a cheap SQL COUNT; everything else falls back to evaluating every matching row server-side, which is exact but not free on a large Base. Both `viewId` and `filters` require `baseId`.",
 		successDescription: "Total active records matching the scope: the whole space, one Base, a saved View, an ad-hoc filter set, or a combination."
 	}).input(countRecordsInputSchema).output(countRecordsResponseSchema),
+	groupBy: oc.route({
+		method: "GET",
+		path: "/records/group-by",
+		tags: ["Records"],
+		summary: "Count records per group",
+		description: "One SQL GROUP BY returning every bucket's exact count — the split a board column header or a summary tile needs, without reading the records themselves. `fieldSlug` must name a `select` or `checkbox` field: their stored value IS the grouping key, so the buckets are exactly the ones a client would build. Grouping by a text, number or date field is rejected rather than approximated (text keys are truncated at the projection limit; date keys would bucket by the server's timezone, not the viewer's). `viewId` and `filters` narrow the set first, with the same exactness rules as `records.count`: provably-exact conditions stay a cheap SQL aggregate, anything else falls back to evaluating every matching row server-side — exact, but not free on a large Base. Groups come back keyed by raw choice id (or `\"true\"`/`\"false\"`), with `null` for records that have no value; labels are the client's to render.",
+		successDescription: "Every group's exact count, plus the total across all groups. Groups with zero records are omitted — a Base's full choice list lives in its field definition, so the client already knows which buckets to render empty."
+	}).errors({
+		BAD_REQUEST: {
+			status: 400,
+			message: "Field is not groupable"
+		},
+		NOT_FOUND: {
+			status: 404,
+			message: "Base or field not found"
+		}
+	}).input(groupRecordsInputSchema).output(groupRecordsResponseSchema),
 	get: oc.route({
 		method: "GET",
 		path: "/records/get",
@@ -2836,19 +3122,55 @@ const ExportAssetTextVOSchema = z.object({
 	textContentHash: z.string().nullable(),
 	byteCount: z.number().int().nonnegative()
 });
-const ImportBeginInputSchema = z.object({ 
+const ExportDocBodiesInputSchema = z.object({ nodeIds: z.array(z.string()).min(1).max(25) });
+const ExportDocBodiesVOSchema = z.object({ 
 /**
-* The space id the archive was ORIGINALLY exported from (`manifest.spaceId`
-* in the `.bbdump`, already integrity-verified before this is called).
-* `importTableRows`'s "nodes" handling needs this to recognize the
-* archive's own root-node row deterministically (`rootNodeIdForSpace`) —
-* scanning each batch's rows for "the one with a null `parentId`" only
-* works when that row happens to land in the SAME batch as its children,
-* which cursor pagination (id-ordered, not tree-ordered) does not
-* guarantee once a space has more nodes than one page. See the matching
-* comment in `import-logic.ts`.
+* One entry per requested node that is a Doc in this space. A node id that
+* does not resolve is simply absent (not an error): the caller asked for a
+* batch, and one bad id must not cost it the other 24. A Doc that exists but
+* has no body object yet yields `markdown: ""`, matching what a read through
+* the Doc domain would return.
 */
-sourceSpaceId: z.string() });
+bodies: z.array(z.object({
+	nodeId: z.string(),
+	markdown: z.string()
+})) });
+const ImportBeginInputSchema = z.object({
+	/**
+	* The space id the archive was ORIGINALLY exported from (`manifest.spaceId`
+	* in the `.bbdump`, already integrity-verified before this is called).
+	* `importTableRows`'s "nodes" handling needs this to recognize the
+	* archive's own root-node row deterministically (`rootNodeIdForSpace`) —
+	* scanning each batch's rows for "the one with a null `parentId`" only
+	* works when that row happens to land in the SAME batch as its children,
+	* which cursor pagination (id-ordered, not tree-ordered) does not
+	* guarantee once a space has more nodes than one page. See the matching
+	* comment in `import-logic.ts`.
+	*/
+	sourceSpaceId: z.string(),
+	/**
+	* Continue a restore that was interrupted partway through, instead of
+	* requiring an empty space.
+	*
+	* A restore that FAILS rolls itself back (`importAbort`), so the target is
+	* left clean and a plain re-run works. What cannot roll itself back is a
+	* restore whose process died — Ctrl-C, OOM, a dropped connection, the
+	* machine rebooting. That leaves the space holding however many of the
+	* archive's rows had landed, and every subsequent attempt is refused
+	* ("requires an empty target space") with no way forward except wiping it.
+	*
+	* In this mode the empty-space guard is skipped and inserts become
+	* `ON CONFLICT DO NOTHING`, so replaying the same archive re-lands only what
+	* is missing. Blobs and doc bodies are content-addressed writes to object
+	* storage and were already idempotent.
+	*
+	* DANGEROUS if pointed at the wrong space: rows that collide are silently
+	* skipped rather than reported, so restoring archive A into a space holding
+	* archive B's data would interleave the two instead of refusing. Only pass
+	* it to continue the SAME archive into the SAME space.
+	*/
+	resume: z.boolean().optional().default(false)
+});
 const ImportBeginVOSchema = z.object({ sessionId: z.string() });
 /**
 * `docBodies`, `attachmentBlobs` and `assetTextBlobs` are pseudo-tables: doc
@@ -2906,6 +3228,13 @@ const dumpContract = {
 		summary: "Resolve the download URL for one asset's extracted-text object",
 		successDescription: "A resolved download URL for the asset's DERIVED text blob (`asset-texts/blobs/sha256/…`) plus its `textStorageKey` and `textContentHash`, so a backup can archive the exact bytes and verify them. `downloadUrl` is null when the row owns no separate object (auto-registered text-kind rows point at their attachment's own key, already covered by the attachment blobs; `status: \"none\"` rows have no text at all)."
 	}).input(ExportAssetTextInputSchema).output(ExportAssetTextVOSchema),
+	exportDocBodies: oc.route({
+		method: "POST",
+		path: "/dump/export/doc-bodies",
+		tags: ["Dump"],
+		summary: "Read the raw markdown for a batch of Doc nodes",
+		successDescription: "The raw body behind each requested Doc, read straight from object storage — archived Docs included, which the ordinary `nodes.get` deliberately refuses. Ids that do not resolve to a Doc in this space are omitted rather than failing the batch."
+	}).input(ExportDocBodiesInputSchema).output(ExportDocBodiesVOSchema),
 	importBegin: oc.route({
 		method: "POST",
 		path: "/dump/import/begin",
@@ -4458,6 +4787,27 @@ const busabaseContractRoutes = {
 			summary: "Update node metadata",
 			successDescription: "Shallow-merged the supplied top-level keys into the active node's existing metadata. Requires write access on the node. Node CONTENT (a Doc body, or a whiteboard/workflow/html document) does not go through here — use PUT /nodes/{nodeId}/content instead."
 		}).input(updateNodeMetadataInputSchema).output(nodeSchema),
+		updateSettings: oc.route({
+			method: "PATCH",
+			path: "/nodes/{nodeId}/settings",
+			tags: ["Nodes"],
+			summary: "Update node system settings",
+			successDescription: "Replaced the node's system settings. Unlike metadata this is a closed set of keys Busabase itself acts on, so an unknown key is rejected rather than stored. Send a key as null to clear it — for an AirApp's engine that returns the node to following its airapp.json. Requires write access on the node."
+		}).input(updateNodeSettingsInputSchema).output(nodeSchema),
+		getAgentPrompts: oc.route({
+			method: "GET",
+			path: "/nodes/{nodeId}/agent-prompts",
+			tags: ["Nodes"],
+			summary: "Get node custom agent prompts",
+			successDescription: "This node's custom scenario prompts, which replace the node type's default prompts in the Ask-agent dialog. `null` means the node has never had any set, which is not the same as an empty list. Read separately from the node itself because the list is large enough (50 prompts x 8 KiB per locale) that carrying it on every node listing would be its own problem. Requires read access on the node."
+		}).input(getNodeAgentPromptsInputSchema).output(nodeAgentPromptsSchema),
+		updateAgentPrompts: oc.route({
+			method: "PUT",
+			path: "/nodes/{nodeId}/agent-prompts",
+			tags: ["Nodes"],
+			summary: "Replace node custom agent prompts",
+			successDescription: "Replaced this node's custom scenario prompts — the whole list, not a merge. Send `null` to clear them and return the node to its type's default prompts. Requires write access on the node."
+		}).input(updateNodeAgentPromptsInputSchema).output(nodeAgentPromptsSchema),
 		updateContent: oc.route({
 			method: "PUT",
 			path: "/nodes/{nodeId}/content",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "busabase-sdk",
-  "version": "0.30.1",
+  "version": "0.40.1",
   "description": "Typed TypeScript/JavaScript SDK for the Busabase OpenAPI REST API. Talks to a local or remote `busabase server` (or Busabase Cloud).",
   "license": "MIT",
   "homepage": "https://github.com/busabase/busabase/tree/main/apps/busabase-sdk",
@@ -68,8 +68,8 @@
     "typescript": "^7.0.2",
     "vitest": "^4.1.11",
     "open-domains": "0.0.2",
-    "openlib": "0.1.1",
-    "busabase-contract": "0.30.1"
+    "busabase-contract": "0.40.1",
+    "openlib": "0.1.1"
   },
   "engines": {
     "node": ">=24.18.0"