busabase-sdk 0.9.2 → 0.9.4

package/dist/index.js

@@ -56,6 +56,7 @@ var ConfirmUploadVOSchema = z.object({
   storageKey: z.string(),
   publicUrl: z.string()
 });
+var AssetTextStatusSchema = z.enum(["missing", "present", "none", "stale"]);
 var AssetVOSchema = z.object({
   id: z.string(),
   attachmentId: z.string(),
@@ -69,6 +70,8 @@ var AssetVOSchema = z.object({
   contentHash: z.string().nullable(),
   /** How many places reference this asset (Base records + Doc bodies). */
   usageCount: z.number().int().nonnegative(),
+  /** Drive Grep Retrieval text-slot status — see {@link AssetTextStatusSchema}. */
+  textStatus: AssetTextStatusSchema,
   createdAt: z.string()
 });
 var AssetUsageVOSchema = z.object({
@@ -92,6 +95,108 @@ var AssetDetailVOSchema = z.object({
   asset: AssetVOSchema,
   usages: z.array(AssetUsageVOSchema)
 });
+var PutTextInputSchema = z.object({
+  assetId: z.string(),
+  /** Inline text body, ≤ 1 MB. For larger text, use `createTextUploadUrl` + bind by `storageKey`. */
+  text: z.string().optional(),
+  /** Bind a presigned-uploaded text object (a temp `asset-texts/pending/*.txt` key). */
+  storageKey: z.string().optional(),
+  /**
+   * Claimed content hash for the `storageKey` bind path (`sha256:<hex>`, echoing
+   * `createTextUploadUrl`'s input like `open-domains/attachments`' confirm step).
+   * The server always computes the ACTUAL hash from the bytes during the
+   * confirm scan and rejects a mismatch (hash-poisoning defense) — this field
+   * is only an optional early-mismatch check, never trusted for addressing.
+   */
+  contentHash: z.string().optional(),
+  /** Mark as having no extractable text (e.g. a scanned, image-only PDF). */
+  none: z.boolean().optional()
+});
+var AssetTextVOSchema = z.object({
+  assetId: z.string(),
+  textStatus: AssetTextStatusSchema,
+  lineCount: z.number().int().nonnegative(),
+  charCount: z.number().int().nonnegative(),
+  byteCount: z.number().int().nonnegative()
+});
+var CreateTextUploadUrlInputSchema = z.object({
+  assetId: z.string(),
+  sizeBytes: z.number().int().positive(),
+  /** Optional claim, mirrors `RequestUploadUrlDTO.contentHash` (never trusted for addressing). */
+  contentHash: z.string().optional()
+});
+var CreateTextUploadUrlVOSchema = z.object({
+  uploadUrl: z.string(),
+  storageKey: z.string(),
+  expiresIn: z.number().int().nonnegative()
+});
+var GrepScopeSchema = z.object({
+  assetIds: z.array(z.string()).optional(),
+  /** Drive/Skill mounted path prefix (matches `busabase_asset_usages.path`). */
+  drivePath: z.string().optional(),
+  mimeTypes: z.array(z.string()).optional()
+});
+var GREP_DEFAULT_MAX_MATCHES = 100;
+var GREP_HARD_MAX_MATCHES = 1e3;
+var GREP_DEFAULT_CONTEXT_LINES = 0;
+var GREP_MAX_CONTEXT_LINES = 10;
+var GrepInputSchema = z.object({
+  pattern: z.string().min(1),
+  /** JS RegExp flags, e.g. `"i"` for case-insensitive. `g`/`y` are ignored (grep always scans every match per line). */
+  flags: z.string().optional().default(""),
+  scope: GrepScopeSchema.optional(),
+  maxMatches: z.coerce.number().int().min(1).max(GREP_HARD_MAX_MATCHES).optional().default(GREP_DEFAULT_MAX_MATCHES),
+  contextLines: z.coerce.number().int().min(0).max(GREP_MAX_CONTEXT_LINES).optional().default(GREP_DEFAULT_CONTEXT_LINES)
+});
+var GrepMatchVOSchema = z.object({
+  assetId: z.string(),
+  fileName: z.string(),
+  /** Drive/Skill mounted path, or "" when the asset isn't path-mounted (e.g. a File node). */
+  drivePath: z.string(),
+  line: z.number().int().positive(),
+  /** 1-based character column (not byte offset) of the match start within the line. */
+  column: z.number().int().positive(),
+  /** The matching line, truncated if it exceeds the long-line guard. */
+  text: z.string(),
+  before: z.array(z.string()),
+  after: z.array(z.string())
+});
+var GrepResultVOSchema = z.object({
+  matches: z.array(GrepMatchVOSchema),
+  filesScanned: z.number().int().nonnegative(),
+  /** Asset ids in scope with no text yet (contentKind text-or-writable-binary, no row). */
+  missing: z.array(z.string()),
+  /** Asset ids in scope whose derived text is stale (source replaced since it was written). */
+  stale: z.array(z.string()),
+  /** Count of assets in scope explicitly marked `none` (no extractable text). */
+  unsearchable: z.number().int().nonnegative(),
+  /**
+   * Asset ids whose scan was attempted but failed (storage error, corrupt
+   * cache file, object deleted mid-flight) — NOT counted in `filesScanned`.
+   * Honest coverage: these were not actually searched, so a caller must not
+   * treat their absence from `matches` as a clean "no match".
+   */
+  errored: z.array(z.string()),
+  /**
+   * Count of in-scope, present-and-searchable assets the scan never even
+   * reached because the deadline or `maxMatches` budget ran out first. Only
+   * nonzero when `truncated` is true.
+   */
+  notReached: z.number().int().nonnegative(),
+  truncated: z.boolean()
+});
+var ReadTextLinesInputSchema = z.object({
+  assetId: z.string(),
+  startLine: z.coerce.number().int().min(1),
+  endLine: z.coerce.number().int().min(1)
+});
+var ReadLinesVOSchema = z.object({
+  lines: z.array(z.string()),
+  startLine: z.number().int().positive(),
+  endLine: z.number().int().positive(),
+  totalLines: z.number().int().nonnegative(),
+  truncated: z.boolean()
+});
 
 // ../../packages/busabase-contract/src/domains/assets/contract.ts
 var UpdateAssetMetadataInputSchema = z.object({
@@ -133,7 +238,7 @@ var assetsContract = {
     path: "/assets/{assetId}/metadata",
     tags: ["Assets"],
     summary: "Update asset metadata",
-    successDescription: "Updated AI-readable metadata for a file, such as summary, extracted text, tags, source URL, or schema-specific hints."
+    successDescription: "Updated AI-readable metadata for a file, such as summary, tags, source URL, or schema-specific hints. Large text does not live here \u2014 see putText / grep / readTextLines."
   }).input(UpdateAssetMetadataInputSchema).output(AssetDetailVOSchema),
   delete: oc.route({
     method: "DELETE",
@@ -141,7 +246,39 @@ var assetsContract = {
     tags: ["Assets"],
     summary: "Delete asset",
     successDescription: "Removed the asset and, if no other row references its bytes, the stored object. Refused while the asset is still referenced (where-used)."
-  }).input(z.object({ assetId: z.string() })).output(z.object({ deleted: z.boolean() }))
+  }).input(z.object({ assetId: z.string() })).output(z.object({ deleted: z.boolean() })),
+  // ── Drive Grep Retrieval ─────────────────────────────────────────────────
+  // Busabase stores, indexes, and searches text; it never generates it. Text
+  // always arrives via putText — an agent's own extractor, or (future) an
+  // Outgoing-Hook-triggered service — never a bundled parser/OCR library.
+  putText: oc.route({
+    method: "PUT",
+    path: "/assets/{assetId}/text",
+    tags: ["Assets"],
+    summary: "Write (or mark none) an asset's text slot",
+    successDescription: "Text slot updated: inline body (\u22641MB), or bound from a presigned upload (server-verified content hash, hash-poisoning-safe), or marked `none` for files with no extractable text. Direct write, audit-logged, not ChangeRequest-gated."
+  }).input(PutTextInputSchema).output(AssetTextVOSchema),
+  createTextUploadUrl: oc.route({
+    method: "POST",
+    path: "/assets/text/upload-urls",
+    tags: ["Assets"],
+    summary: "Request a presigned upload URL for large text",
+    successDescription: "Presigned (or dev) upload URL for a temporary text object; PUT the bytes there, then call putText with the returned storageKey to bind, verify, and content-address it."
+  }).input(CreateTextUploadUrlInputSchema).output(CreateTextUploadUrlVOSchema),
+  grep: oc.route({
+    method: "POST",
+    path: "/assets/grep",
+    tags: ["Assets"],
+    summary: "Search every text-bearing asset in scope",
+    successDescription: "Streaming regex/literal matches with real file + line + column numbers and context, across every asset with text \u2014 any size, no 256KB cap. Honest coverage: missing/stale/unsearchable/errored name assets that were not (fully or successfully) searched, notReached counts present assets the scan never got to, and truncated flags a capped response."
+  }).input(GrepInputSchema).output(GrepResultVOSchema),
+  readTextLines: oc.route({
+    method: "GET",
+    path: "/assets/{assetId}/text/lines",
+    tags: ["Assets"],
+    summary: "Read an exact line range from an asset's text",
+    successDescription: "Lines [startLine, endLine] (range capped at 2000 lines / ~2MB response) read via a storage byte-range request \u2014 the server never loads the whole object, even for a multi-GB file."
+  }).input(ReadTextLinesInputSchema).output(ReadLinesVOSchema)
 };
 var i18n = {
   locales: ["en", "zh-CN", "zh-TW", "ja", "ko", "de", "fr", "es", "pt"]};
@@ -170,6 +307,7 @@ var fieldTypeSchema = z.enum([
   "select",
   "multiselect",
   "url",
+  "embed",
   "email",
   "phone",
   "created_time",
@@ -207,6 +345,11 @@ var fieldOptionsSchema = z.object({
   code: z.object({
     language: z.string().optional()
   }).optional(),
+  embed: z.object({
+    aspectRatio: z.enum(["16:9", "4:3", "1:1"]).optional(),
+    height: z.number().int().positive().max(1200).optional(),
+    providers: z.array(z.string()).optional()
+  }).optional(),
   inverseFieldId: z.string().optional(),
   multiple: z.boolean().optional(),
   // Display formatting for `number` columns (Notion-style: one number type,
@@ -257,7 +400,12 @@ var createBaseInputSchema = z.object({
       required: z.boolean().default(false),
       options: fieldOptionsSchema.optional().default({})
     })
-  ).default([])
+  ).default([]),
+  // Review-first by default: without `autoMerge: true`, this proposes the Base
+  // as a pending ChangeRequest (status "in_review") instead of creating it
+  // immediately. Pass `autoMerge: true` only for callers that don't need human
+  // review (seed/migration scripts, an explicit no-review agent task).
+  autoMerge: z.boolean().optional().default(false)
 });
 var createBaseFieldInputSchema = z.object({
   name: fieldNameSchema,
@@ -629,20 +777,21 @@ var commentSchema = z.object({
   createdAt: z.string(),
   updatedAt: z.string()
 });
+var changeRequestStatusSchema = z.enum([
+  "in_review",
+  "changes_requested",
+  "approved",
+  "rejected",
+  "merged",
+  "abandoned",
+  "conflict"
+]);
 var changeRequestSchema = z.object({
   id: z.string(),
   baseId: z.string().nullable(),
   targetType: z.enum(["base", "node"]),
   nodeId: z.string().nullable(),
-  status: z.enum([
-    "in_review",
-    "changes_requested",
-    "approved",
-    "rejected",
-    "merged",
-    "abandoned",
-    "conflict"
-  ]),
+  status: changeRequestStatusSchema,
   submittedBy: z.string(),
   submittedByUser: userRefSchema.nullable().optional().default(null),
   sourceMeta: z.record(z.string(), z.unknown()),
@@ -688,7 +837,14 @@ var liveEventSchema = z.object({
     "change_request.updated",
     "change_request.deleted",
     "change_request.reviewed",
-    "change_request.merged"
+    "change_request.merged",
+    // Fired only when a CONTENT change request freshly enters human review
+    // (record_* ops created via record-ops.ts) — never for structural ops
+    // that auto-merge instantly (those still fire "change_request.created"
+    // via the audit funnel, but nothing needs reviewing). Consumed by
+    // `use-live-sync.ts` to pop a desktop Notification, and by
+    // busabase-cloud's host hook to persist an inbox notification row.
+    "change_request.pending_review"
   ]),
   spaceId: z.string(),
   actorId: z.string(),
@@ -718,6 +874,8 @@ var auditActionSchema = z.enum([
   "drive.created",
   "asset.deleted",
   "asset.metadata_updated",
+  "asset.text_written",
+  "asset.text_marked_none",
   "node.purged"
 ]);
 var auditEventSchema = z.object({
@@ -838,6 +996,25 @@ var createCommentInputSchema = commentSubjectInputSchema.extend({
 var listInputSchema = z.object({
   limit: z.coerce.number().int().min(1).max(100).optional().default(50)
 }).optional().default({ limit: 50 });
+var listChangeRequestsPagedInputSchema = z.object({
+  limit: z.coerce.number().int().min(1).max(100).optional().default(50),
+  /** Opaque base64 cursor (`createdAt|id`) for keyset pagination. */
+  cursor: z.string().optional(),
+  status: z.array(changeRequestStatusSchema).optional(),
+  mine: z.boolean().optional()
+}).optional().default({ limit: 50 });
+var listChangeRequestsResponseSchema = z.object({
+  changeRequests: z.array(changeRequestSchema),
+  nextCursor: z.string().nullable()
+});
+var changeRequestCountsSchema = z.object({
+  review: z.number().int().nonnegative(),
+  changes: z.number().int().nonnegative(),
+  created: z.number().int().nonnegative(),
+  approved: z.number().int().nonnegative(),
+  merged: z.number().int().nonnegative(),
+  rejected: z.number().int().nonnegative()
+});
 var searchInputSchema = z.object({
   query: z.string().default(""),
   limit: z.coerce.number().int().min(1).max(100).optional().default(20),
@@ -872,6 +1049,69 @@ var authInfoSchema = z.object({
    */
   spaces: z.array(authSpaceSchema)
 });
+var viewFilterOperatorSchema = z.enum([
+  "contains",
+  "equals",
+  "not_empty",
+  "is_empty",
+  "is_true",
+  "is_false"
+]);
+var viewFilterSchema = z.object({
+  fieldSlug: z.string(),
+  // Stable field identity — survives slug reuse; populated on merge.
+  fieldId: z.string().optional(),
+  operator: viewFilterOperatorSchema,
+  value: z.unknown().optional()
+});
+var viewSortSchema = z.object({
+  direction: z.enum(["asc", "desc"]),
+  fieldSlug: z.string(),
+  fieldId: z.string().optional()
+});
+var viewConfigSchema = z.object({
+  filters: z.array(viewFilterSchema).default([]),
+  sorts: z.array(viewSortSchema).default([]),
+  visibleFieldSlugs: z.array(z.string()).nullable().optional()
+});
+var viewSchema = z.object({
+  id: z.string(),
+  baseId: z.string(),
+  slug: z.string(),
+  name: z.string(),
+  description: z.string(),
+  type: z.literal("table"),
+  config: viewConfigSchema,
+  status: z.enum(["active", "archived"]),
+  createdBy: z.string(),
+  createdByUser: userRefSchema.nullable().optional().default(null),
+  archivedAt: z.string().nullable(),
+  createdAt: z.string(),
+  updatedAt: z.string()
+});
+var createViewInputSchema = z.object({
+  config: viewConfigSchema.optional().default({ filters: [], sorts: [] }),
+  description: z.string().optional().default(""),
+  message: z.string().optional().default("Create view"),
+  name: z.string().min(1),
+  slug: z.string().min(1).regex(/^[a-z0-9-]+$/).optional(),
+  submittedBy: z.string().optional().default("local-producer")
+});
+var updateViewInputSchema = z.object({
+  config: viewConfigSchema.optional(),
+  description: z.string().optional(),
+  message: z.string().optional().default("Update view"),
+  name: z.string().min(1).optional(),
+  submittedBy: z.string().optional().default("local-producer")
+});
+var deleteViewInputSchema = z.object({
+  message: z.string().optional().default("Delete view"),
+  submittedBy: z.string().optional().default("local-producer")
+});
+var restoreViewInputSchema = z.object({
+  message: z.string().optional().default("Restore view"),
+  submittedBy: z.string().optional().default("local-producer")
+});
 
 // ../../packages/busabase-contract/src/domains/base/contract/record-schemas.ts
 var recordSchema = z.object({
@@ -889,16 +1129,44 @@ var recordSchema = z.object({
   base: baseSchema,
   headCommit: commitSchema
 });
+var listRecordsFilterSchema = z.object({
+  fieldSlug: z.string(),
+  fieldType: z.string().optional(),
+  operator: viewFilterOperatorSchema,
+  value: z.unknown().optional()
+});
+var listRecordsSortSchema = z.object({
+  fieldSlug: z.string(),
+  fieldType: z.string().optional(),
+  direction: z.enum(["asc", "desc"]).optional().default("asc")
+});
 var listRecordsInputSchema = z.object({
   limit: z.coerce.number().int().min(1).max(100).optional().default(50),
   baseId: z.string().optional(),
-  /** Opaque base64 cursor (`createdAt:id`) for keyset pagination. */
-  cursor: z.string().optional()
+  /** Opaque base64 cursor for keyset pagination (createdAt-keyed, or sort-keyed when `sort` is set). */
+  cursor: z.string().optional(),
+  /** View filters for server-side push-down (superset; client still narrows). */
+  filters: z.array(listRecordsFilterSchema).optional(),
+  /** View sort for server-side push-down (number/date fields only). */
+  sort: listRecordsSortSchema.optional()
 }).optional().default({ limit: 50 });
 var listRecordsResponseSchema = z.object({
   records: z.array(recordSchema),
   nextCursor: z.string().nullable()
 });
+var listArchivedRecordsPagedInputSchema = z.object({
+  baseId: z.string(),
+  limit: z.coerce.number().int().min(1).max(100).optional().default(50),
+  /** Opaque base64 cursor (createdAt-keyed) for keyset pagination. */
+  cursor: z.string().optional()
+});
+var countRecordsInputSchema = z.object({
+  baseId: z.string().optional()
+}).optional().default({});
+var countRecordsResponseSchema = z.object({
+  /** Total active records in the space (optionally scoped to a base). */
+  total: z.number().int().nonnegative()
+});
 var 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 \u2014 always give it a short, human-readable value, never an id or placeholder."
@@ -940,71 +1208,6 @@ var recordLinkSchema = z.object({
   createdAt: z.string(),
   updatedAt: z.string()
 });
-var viewFilterOperatorSchema = z.enum([
-  "contains",
-  "equals",
-  "not_empty",
-  "is_empty",
-  "is_true",
-  "is_false"
-]);
-var viewFilterSchema = z.object({
-  fieldSlug: z.string(),
-  // Stable field identity — survives slug reuse; populated on merge.
-  fieldId: z.string().optional(),
-  operator: viewFilterOperatorSchema,
-  value: z.unknown().optional()
-});
-var viewSortSchema = z.object({
-  direction: z.enum(["asc", "desc"]),
-  fieldSlug: z.string(),
-  fieldId: z.string().optional()
-});
-var viewConfigSchema = z.object({
-  filters: z.array(viewFilterSchema).default([]),
-  sorts: z.array(viewSortSchema).default([]),
-  visibleFieldSlugs: z.array(z.string()).nullable().optional()
-});
-var viewSchema = z.object({
-  id: z.string(),
-  baseId: z.string(),
-  slug: z.string(),
-  name: z.string(),
-  description: z.string(),
-  type: z.literal("table"),
-  config: viewConfigSchema,
-  status: z.enum(["active", "archived"]),
-  createdBy: z.string(),
-  createdByUser: userRefSchema.nullable().optional().default(null),
-  archivedAt: z.string().nullable(),
-  createdAt: z.string(),
-  updatedAt: z.string()
-});
-var createViewInputSchema = z.object({
-  config: viewConfigSchema.optional().default({ filters: [], sorts: [] }),
-  description: z.string().optional().default(""),
-  message: z.string().optional().default("Create view"),
-  name: z.string().min(1),
-  slug: z.string().min(1).regex(/^[a-z0-9-]+$/).optional(),
-  submittedBy: z.string().optional().default("local-producer")
-});
-var updateViewInputSchema = z.object({
-  config: viewConfigSchema.optional(),
-  description: z.string().optional(),
-  message: z.string().optional().default("Update view"),
-  name: z.string().min(1).optional(),
-  submittedBy: z.string().optional().default("local-producer")
-});
-var deleteViewInputSchema = z.object({
-  message: z.string().optional().default("Delete view"),
-  submittedBy: z.string().optional().default("local-producer")
-});
-var restoreViewInputSchema = z.object({
-  message: z.string().optional().default("Restore view"),
-  submittedBy: z.string().optional().default("local-producer")
-});
-
-// ../../packages/busabase-contract/src/domains/base/contract/routes.ts
 var baseContract = {
   list: oc.route({
     method: "GET",
@@ -1055,13 +1258,20 @@ var baseContract = {
     summary: "List archived records for a Base",
     successDescription: "Records that have been archived (soft-deleted) from a Base."
   }).input(z.object({ baseId: z.string() })).output(z.array(recordSchema)),
+  listArchivedRecordsPaged: oc.route({
+    method: "GET",
+    path: "/bases/{baseId}/records/archived/paged",
+    tags: ["Records"],
+    summary: "List archived records for a Base with keyset pagination",
+    successDescription: "A page of archived (soft-deleted) records plus an opaque nextCursor (null at the end)."
+  }).input(listArchivedRecordsPagedInputSchema).output(listRecordsResponseSchema),
   create: oc.route({
     method: "POST",
     path: "/bases",
     tags: ["Bases"],
     summary: "Create Base",
-    successDescription: "Created Base."
-  }).input(createBaseInputSchema).output(baseSchema),
+    successDescription: "Review-first by default: a pending ChangeRequest proposing the Base. Returns the materialized Base instead when `autoMerge: true` is passed."
+  }).input(createBaseInputSchema).output(z.union([baseSchema, changeRequestSchema])),
   createChangeRequest: oc.route({
     method: "POST",
     path: "/bases/{baseId}/change-requests",
@@ -1169,6 +1379,13 @@ var recordContract = {
     summary: "List records with keyset pagination",
     successDescription: "A page of canonical records plus an opaque nextCursor (null at the end)."
   }).input(listRecordsInputSchema).output(listRecordsResponseSchema),
+  count: oc.route({
+    method: "GET",
+    path: "/records/count",
+    tags: ["Records"],
+    summary: "Count records",
+    successDescription: "Total active records in the space, optionally scoped to a base."
+  }).input(countRecordsInputSchema).output(countRecordsResponseSchema),
   get: oc.route({
     method: "GET",
     path: "/records/{recordId}",
@@ -1252,7 +1469,12 @@ var createDocInputSchema = z.object({
   slug: z.string().min(1).regex(/^[a-z0-9-]+$/),
   name: z.string().min(1),
   description: z.string().optional().default(""),
-  body: z.string().optional().default("")
+  body: z.string().optional().default(""),
+  // Review-first by default: without `autoMerge: true`, this proposes the Doc
+  // as a pending ChangeRequest (status "in_review") instead of creating it
+  // immediately. Pass `autoMerge: true` only for callers that don't need human
+  // review (seed/migration scripts, an explicit no-review agent task).
+  autoMerge: z.boolean().optional().default(false)
 });
 var updateDocInputSchema = z.object({
   body: z.string()
@@ -1277,8 +1499,8 @@ var docContract = {
     path: "/docs",
     tags: ["Docs"],
     summary: "Create Doc node",
-    successDescription: "Created Doc node and initialized its body."
-  }).input(createDocInputSchema).output(docSchema),
+    successDescription: "Review-first by default: a pending ChangeRequest proposing the Doc. Returns the materialized Doc node instead when `autoMerge: true` is passed."
+  }).input(createDocInputSchema).output(z.union([docSchema, changeRequestSchema])),
   get: oc.route({
     method: "GET",
     path: "/docs/{nodeId}",
@@ -1350,7 +1572,12 @@ var createFileTreeInputSchema = z.object({
   description: z.string().optional().default(""),
   visibility: z.enum(["private", "workspace", "public"]).optional().default("private"),
   version: z.string().optional().default("0.1.0"),
-  files: z.array(z.union([assetFileInputSchema, textFileInputSchema])).optional().default([])
+  files: z.array(z.union([assetFileInputSchema, textFileInputSchema])).optional().default([]),
+  // Review-first by default: without `autoMerge: true`, this proposes the node
+  // as a pending ChangeRequest (status "in_review") instead of creating it
+  // immediately. Pass `autoMerge: true` only for callers that don't need human
+  // review (seed/migration scripts, an explicit no-review agent task).
+  autoMerge: z.boolean().optional().default(false)
 });
 var fileTreeFileOperationInputSchema = z.union([
   assetFileOperationInputSchema,
@@ -1392,8 +1619,8 @@ var makeFileTreeContract = (routeBase, tag) => {
       path: basePath,
       tags: [tag],
       summary: `Create ${label} node`,
-      successDescription: `Created ${label} node and initialized file tree.`
-    }).input(createFileTreeInputSchema).output(fileTreeNodeSchema),
+      successDescription: `Review-first by default: a pending ChangeRequest proposing the ${label} node. Returns the materialized ${label} node instead when \`autoMerge: true\` is passed.`
+    }).input(createFileTreeInputSchema).output(z.union([fileTreeNodeSchema, changeRequestSchema])),
     get: oc.route({
       method: "GET",
       path: `${basePath}/{nodeId}`,
@@ -1453,7 +1680,12 @@ var createFileNodeInputSchema = z.object({
   slug: z.string().min(1).regex(/^[a-z0-9-]+$/),
   name: z.string().min(1),
   description: z.string().optional().default(""),
-  assetId: z.string().min(1)
+  assetId: z.string().min(1),
+  // Review-first by default: without `autoMerge: true`, this proposes the File
+  // node as a pending ChangeRequest (status "in_review") instead of creating it
+  // immediately. Pass `autoMerge: true` only for callers that don't need human
+  // review (seed/migration scripts, an explicit no-review agent task).
+  autoMerge: z.boolean().optional().default(false)
 });
 var fileContract = {
   list: oc.route({
@@ -1468,8 +1700,8 @@ var fileContract = {
     path: "/files",
     tags: ["Files"],
     summary: "Create File node",
-    successDescription: "Created a first-class File node that references an Asset."
-  }).input(createFileNodeInputSchema).output(FileNodeVOSchema),
+    successDescription: "Review-first by default: a pending ChangeRequest proposing the File node. Returns the materialized File node instead when `autoMerge: true` is passed."
+  }).input(createFileNodeInputSchema).output(z.union([FileNodeVOSchema, changeRequestSchema])),
   get: oc.route({
     method: "GET",
     path: "/files/{nodeId}",
@@ -1501,6 +1733,273 @@ var folderContract = {
 
 // ../../packages/busabase-contract/src/domains/skill/contract.ts
 var skillContract = makeFileTreeContract("skills", "Skills");
+var VaultItemKeySchema = z.string().trim().min(1).max(128).regex(/^[A-Z_][A-Z0-9_]*$/, "Use uppercase letters, numbers, and underscores");
+var VaultItemValueSchema = z.string().max(8192);
+var VaultItemKindSchema = z.enum(["secret", "variable"]);
+var VaultScopeTypeSchema = z.enum([
+  "personal",
+  "workspace",
+  "base",
+  "agent",
+  "tool",
+  "api_key"
+]);
+var VaultEnvironmentSchema = z.enum(["local", "development", "staging", "production"]);
+var VaultAccessPolicySchema = z.object({
+  runtime: z.boolean().default(true),
+  reveal: z.boolean().default(true),
+  edit: z.boolean().default(true),
+  share: z.boolean().default(false)
+});
+var VaultItemInputSchema = z.object({
+  id: z.string().optional(),
+  kind: VaultItemKindSchema,
+  key: VaultItemKeySchema,
+  value: VaultItemValueSchema,
+  scopeType: VaultScopeTypeSchema.default("personal"),
+  scopeId: z.string().trim().nullable().optional(),
+  environment: VaultEnvironmentSchema.default("local"),
+  description: z.string().trim().max(512).default(""),
+  access: VaultAccessPolicySchema.default({
+    runtime: true,
+    reveal: true,
+    edit: true,
+    share: false
+  })
+});
+var UpdateVaultSettingsInputSchema = z.object({
+  items: z.array(VaultItemInputSchema).max(200)
+});
+var VaultItemVOSchema = VaultItemInputSchema.extend({
+  id: z.string(),
+  scopeId: z.string().nullable(),
+  updatedAt: z.string(),
+  createdAt: z.string(),
+  lastUsedAt: z.string().nullable()
+});
+var VaultSettingsVOSchema = z.object({
+  ownerId: z.string().nullable(),
+  items: z.array(VaultItemVOSchema),
+  updatedAt: z.string().nullable()
+});
+z.record(VaultItemKeySchema, VaultItemValueSchema).default({});
+var VaultSuccessSchema = z.object({ success: z.boolean() });
+
+// ../../packages/busabase-contract/src/domains/vault/contract.ts
+var vaultContract = {
+  get: oc.route({
+    method: "GET",
+    path: "/vault",
+    tags: ["Vault"],
+    summary: "Get local Vault settings",
+    successDescription: "Local Vault secrets and variables for this Busabase instance."
+  }).output(VaultSettingsVOSchema),
+  update: oc.route({
+    method: "PUT",
+    path: "/vault",
+    tags: ["Vault"],
+    summary: "Replace local Vault settings",
+    successDescription: "Updated local Vault secrets and variables."
+  }).input(UpdateVaultSettingsInputSchema).output(VaultSettingsVOSchema),
+  clear: oc.route({
+    method: "DELETE",
+    path: "/vault",
+    tags: ["Vault"],
+    summary: "Clear local Vault settings",
+    successDescription: "Removed local Vault secrets and variables."
+  }).output(VaultSuccessSchema)
+};
+var WebhookEventTypeSchema = z.enum(["record.created", "ai_mention", "changes_requested"]);
+z.enum(["webhook", "notify_agent", "run_snippet"]);
+var WebhookDeliveryStatusSchema = z.enum(["success", "failed", "skipped"]);
+var WebhookHttpConfigSchema = z.object({
+  targetUrl: z.string().url(),
+  secret: z.string().min(1).max(256).optional(),
+  headers: z.record(z.string(), z.string()).optional()
+});
+var WebhookSnippetConfigSchema = z.object({
+  code: z.string().min(1).max(2e4),
+  timeoutMs: z.number().int().min(100).max(5e3).default(2e3)
+});
+var WebhookHttpConfigVOSchema = z.object({
+  targetUrl: z.string().url(),
+  hasSecret: z.boolean(),
+  headers: z.record(z.string(), z.string()).optional()
+});
+var WebhookSnippetConfigVOSchema = WebhookSnippetConfigSchema;
+var webhookRuleCommonInputFields = {
+  name: z.string().min(1).max(200),
+  eventType: WebhookEventTypeSchema,
+  baseId: z.string().nullable().optional(),
+  enabled: z.boolean().default(true)
+};
+var WebhookRuleInputSchema = z.discriminatedUnion("actionKind", [
+  z.object({
+    ...webhookRuleCommonInputFields,
+    actionKind: z.literal("webhook"),
+    config: WebhookHttpConfigSchema
+  }),
+  z.object({
+    ...webhookRuleCommonInputFields,
+    actionKind: z.literal("notify_agent"),
+    config: WebhookHttpConfigSchema
+  }),
+  z.object({
+    ...webhookRuleCommonInputFields,
+    actionKind: z.literal("run_snippet"),
+    config: WebhookSnippetConfigSchema
+  })
+]);
+var WebhookRuleUpdateInputSchema = z.discriminatedUnion("actionKind", [
+  z.object({
+    id: z.string(),
+    ...webhookRuleCommonInputFields,
+    actionKind: z.literal("webhook"),
+    config: WebhookHttpConfigSchema
+  }),
+  z.object({
+    id: z.string(),
+    ...webhookRuleCommonInputFields,
+    actionKind: z.literal("notify_agent"),
+    config: WebhookHttpConfigSchema
+  }),
+  z.object({
+    id: z.string(),
+    ...webhookRuleCommonInputFields,
+    actionKind: z.literal("run_snippet"),
+    config: WebhookSnippetConfigSchema
+  })
+]);
+var webhookRuleVOCommonFields = {
+  id: z.string(),
+  spaceId: z.string(),
+  baseId: z.string().nullable(),
+  name: z.string(),
+  eventType: WebhookEventTypeSchema,
+  enabled: z.boolean(),
+  createdBy: z.string(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+  lastTriggeredAt: z.string().nullable(),
+  lastStatus: WebhookDeliveryStatusSchema.nullable()
+};
+var WebhookRuleVOSchema = z.discriminatedUnion("actionKind", [
+  z.object({
+    ...webhookRuleVOCommonFields,
+    actionKind: z.literal("webhook"),
+    config: WebhookHttpConfigVOSchema
+  }),
+  z.object({
+    ...webhookRuleVOCommonFields,
+    actionKind: z.literal("notify_agent"),
+    config: WebhookHttpConfigVOSchema
+  }),
+  z.object({
+    ...webhookRuleVOCommonFields,
+    actionKind: z.literal("run_snippet"),
+    config: WebhookSnippetConfigVOSchema
+  })
+]);
+var WebhookDeliveryVOSchema = z.object({
+  id: z.string(),
+  ruleId: z.string(),
+  eventType: WebhookEventTypeSchema,
+  status: WebhookDeliveryStatusSchema,
+  httpStatus: z.number().nullable(),
+  detail: z.string().nullable(),
+  durationMs: z.number().nullable(),
+  createdAt: z.string()
+});
+z.object({}).optional().default({});
+var ListWebhookDeliveriesInputSchema = z.object({
+  ruleId: z.string(),
+  limit: z.coerce.number().int().min(1).max(100).default(20)
+});
+
+// ../../packages/busabase-contract/src/domains/webhook/contract.ts
+var webhookContract = {
+  list: oc.route({
+    method: "GET",
+    path: "/webhooks",
+    tags: ["Webhooks"],
+    summary: "List webhook automation rules",
+    successDescription: "Configured webhook automation rules for this space."
+  }).output(WebhookRuleVOSchema.array()),
+  get: oc.route({
+    method: "GET",
+    path: "/webhooks/{id}",
+    tags: ["Webhooks"],
+    summary: "Get webhook automation rule",
+    successDescription: "A single webhook automation rule."
+  }).input(z.object({ id: z.string() })).output(WebhookRuleVOSchema),
+  create: oc.route({
+    method: "POST",
+    path: "/webhooks",
+    tags: ["Webhooks"],
+    summary: "Create webhook automation rule",
+    successDescription: "Created webhook automation rule. Dispatches on the configured event via an HTTP webhook, an agent notification, or a sandboxed snippet."
+  }).input(WebhookRuleInputSchema).output(WebhookRuleVOSchema),
+  update: oc.route({
+    method: "PUT",
+    path: "/webhooks/{id}",
+    tags: ["Webhooks"],
+    summary: "Update webhook automation rule",
+    successDescription: "Updated webhook automation rule."
+  }).input(WebhookRuleUpdateInputSchema).output(WebhookRuleVOSchema),
+  delete: oc.route({
+    method: "DELETE",
+    path: "/webhooks/{id}",
+    tags: ["Webhooks"],
+    summary: "Delete webhook automation rule",
+    successDescription: "Removed the webhook automation rule."
+  }).input(z.object({ id: z.string() })).output(z.object({ success: z.boolean() })),
+  deliveries: oc.route({
+    method: "GET",
+    path: "/webhooks/{ruleId}/deliveries",
+    tags: ["Webhooks"],
+    summary: "List webhook rule delivery attempts",
+    successDescription: "Recent delivery attempts for a webhook rule, newest first."
+  }).input(ListWebhookDeliveriesInputSchema).output(WebhookDeliveryVOSchema.array()),
+  testFire: oc.route({
+    method: "POST",
+    path: "/webhooks/{id}/test-fire",
+    tags: ["Webhooks"],
+    summary: "Test-fire a webhook automation rule",
+    successDescription: "The delivery record produced by firing this rule right now with a synthetic payload \u2014 runs regardless of the rule's enabled state or its real trigger."
+  }).input(z.object({ id: z.string() })).output(WebhookDeliveryVOSchema)
+};
+var activityItemSchema = z.discriminatedUnion("kind", [
+  z.object({
+    kind: z.literal("change_request"),
+    timestamp: z.string(),
+    changeRequest: changeRequestSchema
+  }),
+  z.object({
+    kind: z.literal("operation"),
+    timestamp: z.string(),
+    operationId: z.string(),
+    changeRequest: changeRequestSchema
+  }),
+  z.object({
+    kind: z.literal("record"),
+    timestamp: z.string(),
+    record: recordSchema
+  }),
+  z.object({
+    kind: z.literal("audit"),
+    timestamp: z.string(),
+    auditEvent: auditEventSchema,
+    record: recordSchema.nullable()
+  })
+]);
+var listActivityPagedInputSchema = z.object({
+  limit: z.coerce.number().int().min(1).max(100).optional().default(50),
+  cursor: z.string().optional()
+}).optional().default({ limit: 50 });
+var listActivityResponseSchema = z.object({
+  items: z.array(activityItemSchema),
+  nextCursor: z.string().nullable()
+});
 
 // ../../packages/busabase-contract/src/contract/busabase.ts
 var changeRequestBatchResultSchema = z.object({
@@ -1576,6 +2075,15 @@ var busabaseContractRoutes = {
       successDescription: "Recorded audit event."
     }).input(createAuditEventInputSchema).output(auditEventSchema)
   },
+  activity: {
+    listPaged: oc.route({
+      method: "GET",
+      path: "/activity/paged",
+      tags: ["Activity"],
+      summary: "List the activity feed with keyset pagination",
+      successDescription: "A page of activity items (change requests, operations, records and audit events merged, newest first) plus an opaque nextCursor (null at the end)."
+    }).input(listActivityPagedInputSchema).output(listActivityResponseSchema)
+  },
   comments: {
     list: oc.route({
       method: "GET",
@@ -1613,6 +2121,8 @@ var busabaseContractRoutes = {
   docs: docContract,
   folders: folderContract,
   assets: assetsContract,
+  vault: vaultContract,
+  webhooks: webhookContract,
   changeRequests: {
     list: oc.route({
       method: "GET",
@@ -1621,6 +2131,20 @@ var busabaseContractRoutes = {
       summary: "List change requests",
       successDescription: "Change requests waiting for review or ready to merge."
     }).input(listInputSchema).output(z.array(changeRequestSchema)),
+    listPaged: oc.route({
+      method: "GET",
+      path: "/change-requests/paged",
+      tags: ["Change Requests"],
+      summary: "List change requests with keyset pagination",
+      successDescription: "A page of change requests plus an opaque nextCursor (null at the end). Filter with `status` and/or `mine`."
+    }).input(listChangeRequestsPagedInputSchema).output(listChangeRequestsResponseSchema),
+    counts: oc.route({
+      method: "GET",
+      path: "/change-requests/counts",
+      tags: ["Change Requests"],
+      summary: "Count change requests by inbox tab",
+      successDescription: "Whole-space change request counts per inbox tab (review / changes / created / approved / merged / rejected)."
+    }).output(changeRequestCountsSchema),
     get: oc.route({
       method: "GET",
       path: "/change-requests/{changeRequestId}",
@@ -1742,6 +2266,7 @@ var notFoundErrors = {
     data: ErrorResponseSchema
   }
 };
+var { vault: _localVault, ...cloudWorkbenchRoutes } = busabaseContractRoutes;
 var cloudExtraRoutes = {
   system: {
     health: oc.route({
@@ -1822,7 +2347,7 @@ var cloudExtraRoutes = {
   }
 };
 var cloudContract = oc.prefix("/api/v1").router({
-  ...busabaseContractRoutes,
+  ...cloudWorkbenchRoutes,
   ...cloudExtraRoutes
 });
 
@@ -1924,10 +2449,48 @@ var Busabase = class {
   get agentTasks() {
     return this.client.agentTasks;
   }
+  get webhooks() {
+    return this.client.webhooks;
+  }
   /** Full-text search across records, change requests, and Bases. */
   search(input) {
     return this.client.search(input);
   }
+  /**
+   * Supply text for an Asset's Drive Grep Retrieval text slot in one call —
+   * inline for small text, a presigned upload for large text — so callers
+   * never see the underlying three-step flow
+   * (`createTextUploadUrl` → PUT bytes → `putText({ storageKey })`).
+   *
+   * @example
+   * ```ts
+   * await bb.putText(assetId, extractedText); // picks inline vs presigned by size
+   * ```
+   */
+  async putText(assetId, text) {
+    const INLINE_TEXT_MAX_BYTES = 1024 * 1024;
+    const byteLength = typeof Buffer !== "undefined" ? Buffer.byteLength(text, "utf8") : new Blob([text]).size;
+    if (byteLength <= INLINE_TEXT_MAX_BYTES) {
+      return this.client.assets.putText({ assetId, text });
+    }
+    const upload = await this.client.assets.createTextUploadUrl({
+      assetId,
+      sizeBytes: byteLength
+    });
+    const doFetch = this.config.fetch ?? fetch;
+    const response = await doFetch(upload.uploadUrl, {
+      method: "PUT",
+      headers: { "content-type": "text/plain; charset=utf-8" },
+      body: text
+    });
+    if (!response.ok) {
+      const detail = await response.text().catch(() => "");
+      throw new Error(
+        `putText: presigned upload failed (${response.status} ${response.statusText})${detail ? `: ${detail}` : ""}`
+      );
+    }
+    return this.client.assets.putText({ assetId, storageKey: upload.storageKey });
+  }
   /** Service health — reaches the server without requiring auth. */
   health() {
     return this.client.system.health();