@inkeep/agents-core 0.0.0-dev-20260120222159 → 0.0.0-dev-20260121022749

package/dist/dolt/branch.d.ts

@@ -54,58 +54,9 @@ declare const doltCheckout: (db: AgentsManageDatabaseClient) => (params: {
 declare const doltActiveBranch: (db: AgentsManageDatabaseClient) => () => Promise<string>;
 declare const doltGetBranchNamespace: (scopes: branchScopes) => () => string;
 /**
- * Execute a callback function with the database connection on a specific branch.
- * After the callback completes (success or error), the connection is returned to the original branch.
- *
- * @param db - The database client
- * @param branchName - The branch to checkout before executing the callback
- * @param callback - The async function to execute while on the specified branch
- * @returns The result of the callback function
- *
- * @example
- * ```ts
- * const result = await withBranch(db)({
- *   branchName: 'default_andrew1_main',
- *   callback: async () => {
- *     return await getFullProjectWithRelationIds(db)({ scopes });
- *   },
- * });
- * ```
+ * Create a branch if it doesn't exist, handling race conditions gracefully.
+ * If multiple concurrent requests try to create the same branch, only one will succeed.
  */
-/**
- * Execute a callback function with the database connection on a specific branch.
- *
- * IMPORTANT: This function uses a transaction to ensure all queries within the callback
- * run on the same database connection. This is critical because DoltGres branching is
- * connection-scoped - a DOLT_CHECKOUT only affects the specific connection that runs it.
- * Without a transaction, subsequent queries might use different connections from the pool
- * that are still on the original branch.
- *
- * After the callback completes (success or error), the connection is returned to the original branch.
- *
- * @param db - The database client
- * @param branchName - The branch to checkout before executing the callback
- * @param callback - The async function to execute while on the specified branch
- * @returns The result of the callback function
- *
- * @example
- * ```ts
- * const result = await withBranch(db)({
- *   branchName: 'default_andrew1_main',
- *   callback: async (txDb) => {
- *     return await getFullProjectWithRelationIds(txDb)({ scopes });
- *   },
- * });
- * ```
- */
-declare const withBranch: (db: AgentsManageDatabaseClient) => <T>(params: {
-  branchName: string;
-  callback: (txDb: AgentsManageDatabaseClient) => Promise<T>;
-}) => Promise<T>;
-/**
- * Generate the standard project branch name from tenant and project IDs.
- * Format: {tenantId}_{projectId}_main
- */
-declare const getProjectBranchName: (tenantId: string, projectId: string) => string;
+declare const ensureBranchExists: (db: AgentsManageDatabaseClient, branchName: string) => Promise<void>;
 //#endregion
-export { branchScopes, doltActiveBranch, doltBranch, doltBranchExists, doltCheckout, doltDeleteBranch, doltGetBranchNamespace, doltListBranches, doltRenameBranch, getProjectBranchName, withBranch };
+export { branchScopes, doltActiveBranch, doltBranch, doltBranchExists, doltCheckout, doltDeleteBranch, doltGetBranchNamespace, doltListBranches, doltRenameBranch, ensureBranchExists };

package/dist/dolt/branch.js

@@ -1,25 +1,9 @@
 import { doltHashOf } from "./commit.js";
+import { resolveRef } from "./ref-helpers.js";
 import { sql } from "drizzle-orm";
+import { logger } from "@composio/core";
 
 //#region src/dolt/branch.ts
-const isDoltCache = /* @__PURE__ */ new WeakMap();
-const isTestEnvironment = process.env.NODE_ENV === "test" || process.env.VITEST === "true";
-/**
-* Check if the database supports Dolt operations (cached per db instance)
-*/
-async function checkIsDolt(db) {
-	if (isTestEnvironment) return false;
-	const cached = isDoltCache.get(db);
-	if (cached !== void 0) return cached;
-	let isDolt = true;
-	try {
-		await db.execute(sql`SELECT ACTIVE_BRANCH() as branch`);
-	} catch {
-		isDolt = false;
-	}
-	isDoltCache.set(db, isDolt);
-	return isDolt;
-}
 /**
 * Create a new branch
 */
@@ -70,71 +54,29 @@ const doltGetBranchNamespace = (scopes) => () => {
 	return `${scopes.tenantId}_${scopes.projectId}_${scopes.branchName}`;
 };
 /**
-* Execute a callback function with the database connection on a specific branch.
-* After the callback completes (success or error), the connection is returned to the original branch.
-*
-* @param db - The database client
-* @param branchName - The branch to checkout before executing the callback
-* @param callback - The async function to execute while on the specified branch
-* @returns The result of the callback function
-*
-* @example
-* ```ts
-* const result = await withBranch(db)({
-*   branchName: 'default_andrew1_main',
-*   callback: async () => {
-*     return await getFullProjectWithRelationIds(db)({ scopes });
-*   },
-* });
-* ```
-*/
-/**
-* Execute a callback function with the database connection on a specific branch.
-*
-* IMPORTANT: This function uses a transaction to ensure all queries within the callback
-* run on the same database connection. This is critical because DoltGres branching is
-* connection-scoped - a DOLT_CHECKOUT only affects the specific connection that runs it.
-* Without a transaction, subsequent queries might use different connections from the pool
-* that are still on the original branch.
-*
-* After the callback completes (success or error), the connection is returned to the original branch.
-*
-* @param db - The database client
-* @param branchName - The branch to checkout before executing the callback
-* @param callback - The async function to execute while on the specified branch
-* @returns The result of the callback function
-*
-* @example
-* ```ts
-* const result = await withBranch(db)({
-*   branchName: 'default_andrew1_main',
-*   callback: async (txDb) => {
-*     return await getFullProjectWithRelationIds(txDb)({ scopes });
-*   },
-* });
-* ```
+* Create a branch if it doesn't exist, handling race conditions gracefully.
+* If multiple concurrent requests try to create the same branch, only one will succeed.
 */
-const withBranch = (db) => async (params) => {
-	const { branchName, callback } = params;
-	if (!await checkIsDolt(db)) return callback(db);
-	return db.transaction(async (tx) => {
-		const originalBranch = (await tx.execute(sql`SELECT ACTIVE_BRANCH() as branch`)).rows[0]?.branch;
-		if (originalBranch === branchName) return callback(tx);
-		try {
-			await tx.execute(sql.raw(`SELECT DOLT_CHECKOUT('${branchName}')`));
-			return await callback(tx);
-		} finally {
-			if (originalBranch !== branchName) await tx.execute(sql.raw(`SELECT DOLT_CHECKOUT('${originalBranch}')`));
+const ensureBranchExists = async (db, branchName) => {
+	if (await resolveRef(db)(branchName)) {
+		logger.debug({ branchName }, "Branch already exists, skipping creation");
+		return;
+	}
+	try {
+		await doltBranch(db)({ name: branchName });
+		logger.debug({ branchName }, "Branch created successfully");
+	} catch (error) {
+		if (await resolveRef(db)(branchName)) {
+			logger.debug({ branchName }, "Branch creation failed but branch exists (concurrent creation), continuing");
+			return;
 		}
-	});
-};
-/**
-* Generate the standard project branch name from tenant and project IDs.
-* Format: {tenantId}_{projectId}_main
-*/
-const getProjectBranchName = (tenantId, projectId) => {
-	return `${tenantId}_${projectId}_main`;
+		logger.error({
+			branchName,
+			error
+		}, "Branch creation failed and branch does not exist");
+		throw error;
+	}
 };
 
 //#endregion
-export { doltActiveBranch, doltBranch, doltBranchExists, doltCheckout, doltDeleteBranch, doltGetBranchNamespace, doltListBranches, doltRenameBranch, getProjectBranchName, withBranch };
+export { doltActiveBranch, doltBranch, doltBranchExists, doltCheckout, doltDeleteBranch, doltGetBranchNamespace, doltListBranches, doltRenameBranch, ensureBranchExists };

package/dist/dolt/branches-api.js

@@ -1,5 +1,5 @@
-import { doltBranch, doltCheckout, doltDeleteBranch, doltGetBranchNamespace, doltListBranches } from "./branch.js";
 import { SCHEMA_SOURCE_BRANCH, ensureSchemaSync, getSchemaDiff, syncSchemaFromMain } from "./schema-sync.js";
+import { doltBranch, doltCheckout, doltDeleteBranch, doltGetBranchNamespace, doltListBranches } from "./branch.js";
 import { sql } from "drizzle-orm";
 
 //#region src/dolt/branches-api.ts

package/dist/dolt/index.d.ts

@@ -1,8 +1,10 @@
-import { branchScopes, doltActiveBranch, doltBranch, doltBranchExists, doltCheckout, doltDeleteBranch, doltGetBranchNamespace, doltListBranches, doltRenameBranch, getProjectBranchName, withBranch } from "./branch.js";
+import { branchScopes, doltActiveBranch, doltBranch, doltBranchExists, doltCheckout, doltDeleteBranch, doltGetBranchNamespace, doltListBranches, doltRenameBranch, ensureBranchExists } from "./branch.js";
 import { CheckoutBranchParams, CheckoutBranchResult, CreateBranchParams, DeleteBranchParams, GetBranchParams, MAIN_BRANCH_SUFFIX, checkoutBranch, createBranch, deleteBranch, getBranch, getTenantMainBranch, isProtectedBranchName, listBranches, listBranchesForAgent } from "./branches-api.js";
 import { doltAdd, doltAddAndCommit, doltCommit, doltDeleteTag, doltHashOf, doltListTags, doltLog, doltReset, doltStatus, doltTag } from "./commit.js";
 import { doltDiff, doltDiffSummary } from "./diff.js";
 import { doltAbortMerge, doltConflicts, doltMerge, doltMergeStatus, doltResolveConflicts, doltSchemaConflicts, doltTableConflicts } from "./merge.js";
-import { RefType, checkoutRef, getCurrentBranchOrCommit, isRefWritable, isValidCommitHash, resolveRef } from "./ref.js";
+import { RefType, checkoutRef, getCurrentBranchOrCommit, getProjectMainResolvedRef, getProjectScopedRef, getTenantScopedRef, isRefWritable, isValidCommitHash, resolveRef } from "./ref-helpers.js";
+import { RefContext, RefMiddlewareOptions, createRefMiddleware, createWriteProtectionMiddleware, refMiddlewareFactory, writeProtectionMiddlewareFactory } from "./ref-middleware.js";
+import { NestedRefScopeError, WithRefOptions, getCurrentRefScope, getRefScopedDb, isInRefScope, withRef } from "./ref-scope.js";
 import { EnsureSchemaSyncOptions, SCHEMA_SOURCE_BRANCH, SchemaDiff, SchemaSyncOptions, SchemaSyncResult, areBranchesSchemaCompatible, ensureSchemaSync, formatSchemaDiffSummary, getActiveBranch, getSchemaDiff, hasSchemaDifferences, hasUncommittedChanges, syncSchemaFromMain } from "./schema-sync.js";
-export { CheckoutBranchParams, CheckoutBranchResult, CreateBranchParams, DeleteBranchParams, EnsureSchemaSyncOptions, GetBranchParams, MAIN_BRANCH_SUFFIX, RefType, SCHEMA_SOURCE_BRANCH, SchemaDiff, SchemaSyncOptions, SchemaSyncResult, areBranchesSchemaCompatible, branchScopes, checkoutBranch, checkoutRef, createBranch, deleteBranch, doltAbortMerge, doltActiveBranch, doltAdd, doltAddAndCommit, doltBranch, doltBranchExists, doltCheckout, doltCommit, doltConflicts, doltDeleteBranch, doltDeleteTag, doltDiff, doltDiffSummary, doltGetBranchNamespace, doltHashOf, doltListBranches, doltListTags, doltLog, doltMerge, doltMergeStatus, doltRenameBranch, doltReset, doltResolveConflicts, doltSchemaConflicts, doltStatus, doltTableConflicts, doltTag, ensureSchemaSync, formatSchemaDiffSummary, getActiveBranch, getBranch, getCurrentBranchOrCommit, getProjectBranchName, getSchemaDiff, getTenantMainBranch, hasSchemaDifferences, hasUncommittedChanges, isProtectedBranchName, isRefWritable, isValidCommitHash, listBranches, listBranchesForAgent, resolveRef, syncSchemaFromMain, withBranch };
+export { CheckoutBranchParams, CheckoutBranchResult, CreateBranchParams, DeleteBranchParams, EnsureSchemaSyncOptions, GetBranchParams, MAIN_BRANCH_SUFFIX, NestedRefScopeError, RefContext, RefMiddlewareOptions, RefType, SCHEMA_SOURCE_BRANCH, SchemaDiff, SchemaSyncOptions, SchemaSyncResult, WithRefOptions, areBranchesSchemaCompatible, branchScopes, checkoutBranch, checkoutRef, createBranch, createRefMiddleware, createWriteProtectionMiddleware, deleteBranch, doltAbortMerge, doltActiveBranch, doltAdd, doltAddAndCommit, doltBranch, doltBranchExists, doltCheckout, doltCommit, doltConflicts, doltDeleteBranch, doltDeleteTag, doltDiff, doltDiffSummary, doltGetBranchNamespace, doltHashOf, doltListBranches, doltListTags, doltLog, doltMerge, doltMergeStatus, doltRenameBranch, doltReset, doltResolveConflicts, doltSchemaConflicts, doltStatus, doltTableConflicts, doltTag, ensureBranchExists, ensureSchemaSync, formatSchemaDiffSummary, getActiveBranch, getBranch, getCurrentBranchOrCommit, getCurrentRefScope, getProjectMainResolvedRef, getProjectScopedRef, getRefScopedDb, getSchemaDiff, getTenantMainBranch, getTenantScopedRef, hasSchemaDifferences, hasUncommittedChanges, isInRefScope, isProtectedBranchName, isRefWritable, isValidCommitHash, listBranches, listBranchesForAgent, refMiddlewareFactory, resolveRef, syncSchemaFromMain, withRef, writeProtectionMiddlewareFactory };

package/dist/dolt/index.js

@@ -1,9 +1,11 @@
 import { doltAdd, doltAddAndCommit, doltCommit, doltDeleteTag, doltHashOf, doltListTags, doltLog, doltReset, doltStatus, doltTag } from "./commit.js";
-import { doltActiveBranch, doltBranch, doltBranchExists, doltCheckout, doltDeleteBranch, doltGetBranchNamespace, doltListBranches, doltRenameBranch, getProjectBranchName, withBranch } from "./branch.js";
 import { doltAbortMerge, doltConflicts, doltMerge, doltMergeStatus, doltResolveConflicts, doltSchemaConflicts, doltTableConflicts } from "./merge.js";
 import { SCHEMA_SOURCE_BRANCH, areBranchesSchemaCompatible, ensureSchemaSync, formatSchemaDiffSummary, getActiveBranch, getSchemaDiff, hasSchemaDifferences, hasUncommittedChanges, syncSchemaFromMain } from "./schema-sync.js";
 import { MAIN_BRANCH_SUFFIX, checkoutBranch, createBranch, deleteBranch, getBranch, getTenantMainBranch, isProtectedBranchName, listBranches, listBranchesForAgent } from "./branches-api.js";
+import { checkoutRef, getCurrentBranchOrCommit, getProjectMainResolvedRef, getProjectScopedRef, getTenantScopedRef, isRefWritable, isValidCommitHash, resolveRef } from "./ref-helpers.js";
+import { doltActiveBranch, doltBranch, doltBranchExists, doltCheckout, doltDeleteBranch, doltGetBranchNamespace, doltListBranches, doltRenameBranch, ensureBranchExists } from "./branch.js";
 import { doltDiff, doltDiffSummary } from "./diff.js";
-import { checkoutRef, getCurrentBranchOrCommit, isRefWritable, isValidCommitHash, resolveRef } from "./ref.js";
+import { createRefMiddleware, createWriteProtectionMiddleware, refMiddlewareFactory, writeProtectionMiddlewareFactory } from "./ref-middleware.js";
+import { NestedRefScopeError, getCurrentRefScope, getRefScopedDb, isInRefScope, withRef } from "./ref-scope.js";
 
-export { MAIN_BRANCH_SUFFIX, SCHEMA_SOURCE_BRANCH, areBranchesSchemaCompatible, checkoutBranch, checkoutRef, createBranch, deleteBranch, doltAbortMerge, doltActiveBranch, doltAdd, doltAddAndCommit, doltBranch, doltBranchExists, doltCheckout, doltCommit, doltConflicts, doltDeleteBranch, doltDeleteTag, doltDiff, doltDiffSummary, doltGetBranchNamespace, doltHashOf, doltListBranches, doltListTags, doltLog, doltMerge, doltMergeStatus, doltRenameBranch, doltReset, doltResolveConflicts, doltSchemaConflicts, doltStatus, doltTableConflicts, doltTag, ensureSchemaSync, formatSchemaDiffSummary, getActiveBranch, getBranch, getCurrentBranchOrCommit, getProjectBranchName, getSchemaDiff, getTenantMainBranch, hasSchemaDifferences, hasUncommittedChanges, isProtectedBranchName, isRefWritable, isValidCommitHash, listBranches, listBranchesForAgent, resolveRef, syncSchemaFromMain, withBranch };
+export { MAIN_BRANCH_SUFFIX, NestedRefScopeError, SCHEMA_SOURCE_BRANCH, areBranchesSchemaCompatible, checkoutBranch, checkoutRef, createBranch, createRefMiddleware, createWriteProtectionMiddleware, deleteBranch, doltAbortMerge, doltActiveBranch, doltAdd, doltAddAndCommit, doltBranch, doltBranchExists, doltCheckout, doltCommit, doltConflicts, doltDeleteBranch, doltDeleteTag, doltDiff, doltDiffSummary, doltGetBranchNamespace, doltHashOf, doltListBranches, doltListTags, doltLog, doltMerge, doltMergeStatus, doltRenameBranch, doltReset, doltResolveConflicts, doltSchemaConflicts, doltStatus, doltTableConflicts, doltTag, ensureBranchExists, ensureSchemaSync, formatSchemaDiffSummary, getActiveBranch, getBranch, getCurrentBranchOrCommit, getCurrentRefScope, getProjectMainResolvedRef, getProjectScopedRef, getRefScopedDb, getSchemaDiff, getTenantMainBranch, getTenantScopedRef, hasSchemaDifferences, hasUncommittedChanges, isInRefScope, isProtectedBranchName, isRefWritable, isValidCommitHash, listBranches, listBranchesForAgent, refMiddlewareFactory, resolveRef, syncSchemaFromMain, withRef, writeProtectionMiddlewareFactory };

package/dist/dolt/migrate-all-branches.js

@@ -1,6 +1,6 @@
 import { createAgentsManageDatabaseClient } from "../db/manage/manage-client.js";
-import { doltCheckout, doltListBranches } from "./branch.js";
 import { syncSchemaFromMain } from "./schema-sync.js";
+import { doltCheckout, doltListBranches } from "./branch.js";
 
 //#region src/dolt/migrate-all-branches.ts
 const ansi = {

package/dist/dolt/{ref.d.ts → ref-helpers.d.ts}

@@ -1,9 +1,11 @@
 import { ResolvedRef } from "../validation/dolt-schemas.js";
 import { AgentsManageDatabaseClient } from "../db/manage/manage-client.js";
 
-//#region src/dolt/ref.d.ts
+//#region src/dolt/ref-helpers.d.ts
 type RefType = 'commit' | 'tag' | 'branch';
 declare const isValidCommitHash: (ref: string) => boolean;
+declare const getProjectScopedRef: (tenantId: string, projectId: string, ref: string) => string;
+declare const getTenantScopedRef: (tenantId: string, ref: string) => string;
 declare const resolveRef: (db: AgentsManageDatabaseClient) => (ref: string) => Promise<ResolvedRef | null>;
 declare const isRefWritable: (resolvedRef: ResolvedRef) => boolean;
 declare const checkoutRef: (db: AgentsManageDatabaseClient) => (resolvedRef: ResolvedRef) => Promise<void>;
@@ -12,5 +14,6 @@ declare const getCurrentBranchOrCommit: (db: AgentsManageDatabaseClient) => () =
   hash: string;
   type: RefType;
 }>;
+declare const getProjectMainResolvedRef: (db: AgentsManageDatabaseClient) => (tenantId: string, projectId: string) => Promise<ResolvedRef>;
 //#endregion
-export { RefType, checkoutRef, getCurrentBranchOrCommit, isRefWritable, isValidCommitHash, resolveRef };
+export { RefType, checkoutRef, getCurrentBranchOrCommit, getProjectMainResolvedRef, getProjectScopedRef, getTenantScopedRef, isRefWritable, isValidCommitHash, resolveRef };

package/dist/dolt/{ref.js → ref-helpers.js}

@@ -1,12 +1,18 @@
 import { doltHashOf, doltListTags } from "./commit.js";
-import { doltListBranches } from "./branch.js";
 import { checkoutBranch } from "./branches-api.js";
+import { doltListBranches } from "./branch.js";
 import { sql } from "drizzle-orm";
 
-//#region src/dolt/ref.ts
+//#region src/dolt/ref-helpers.ts
 const isValidCommitHash = (ref) => {
 	return /^[0-9a-v]{32}$/.test(ref);
 };
+const getProjectScopedRef = (tenantId, projectId, ref) => {
+	return `${tenantId}_${projectId}_${ref}`;
+};
+const getTenantScopedRef = (tenantId, ref) => {
+	return `${tenantId}_${ref}`;
+};
 const resolveRef = (db) => async (ref) => {
 	if (isValidCommitHash(ref)) return {
 		type: "commit",
@@ -48,6 +54,12 @@ const getCurrentBranchOrCommit = (db) => async () => {
 		type: "commit"
 	};
 };
+const getProjectMainResolvedRef = (db) => async (tenantId, projectId) => {
+	const projectMain = `${tenantId}_${projectId}_main`;
+	const resolvedRef = await resolveRef(db)(projectMain);
+	if (!resolvedRef) throw new Error(`Project main branch not found: ${projectMain}`);
+	return resolvedRef;
+};
 
 //#endregion
-export { checkoutRef, getCurrentBranchOrCommit, isRefWritable, isValidCommitHash, resolveRef };
+export { checkoutRef, getCurrentBranchOrCommit, getProjectMainResolvedRef, getProjectScopedRef, getTenantScopedRef, isRefWritable, isValidCommitHash, resolveRef };

package/dist/dolt/ref-middleware.d.ts

@@ -0,0 +1,82 @@
+import { ResolvedRef } from "../validation/dolt-schemas.js";
+import { AgentsManageDatabaseClient } from "../db/manage/manage-client.js";
+import { Context, Next } from "hono";
+
+//#region src/dolt/ref-middleware.d.ts
+type RefContext = {
+  resolvedRef?: ResolvedRef;
+};
+interface RefMiddlewareOptions {
+  /**
+   * Extract tenantId from the request context.
+   * Default implementation extracts from path using /tenants/{tenantId} pattern.
+   */
+  extractTenantId?: (c: Context) => string | undefined;
+  /**
+   * Extract projectId from the request context.
+   * Default implementation extracts from path using /tenants/{tenantId}/projects/{projectId} pattern.
+   */
+  extractProjectId?: (c: Context) => string | undefined;
+  /**
+   * Whether to allow extracting projectId from request body for POST/PUT/PATCH.
+   * Default: true
+   */
+  allowProjectIdFromBody?: boolean;
+  /**
+   * Custom path patterns that should skip ref validation.
+   * Default: []
+   */
+  skipRefValidationPaths?: RegExp[];
+}
+/**
+ * Creates a ref resolution middleware factory.
+ *
+ * This middleware:
+ * 1. Extracts tenantId and projectId from the request
+ * 2. Resolves the `ref` query parameter to a ResolvedRef
+ * 3. Creates branches if needed (tenant_main, project_main)
+ * 4. Sets `resolvedRef` in the Hono context for downstream handlers
+ *
+ * @param db - The Doltgres database client to use for ref resolution
+ * @param options - Optional configuration for extraction and validation
+ * @returns Hono middleware function
+ *
+ * @example
+ * ```typescript
+ * import { createRefMiddleware } from '@inkeep/agents-core';
+ * import { manageDbClient } from './db';
+ *
+ * const refMiddleware = createRefMiddleware(manageDbClient);
+ * app.use('/tenants/*', refMiddleware);
+ * ```
+ */
+declare const createRefMiddleware: (db: AgentsManageDatabaseClient, options?: RefMiddlewareOptions) => (c: Context, next: Next) => Promise<void>;
+/**
+ * Creates a write protection middleware that prevents write operations on immutable refs.
+ *
+ * This middleware checks if the resolved ref is writable (branches are writable,
+ * tags and commits are not) and rejects write operations on immutable refs.
+ *
+ * @returns Hono middleware function
+ *
+ * @example
+ * ```typescript
+ * import { createRefMiddleware, createWriteProtectionMiddleware } from '@inkeep/agents-core';
+ *
+ * const refMiddleware = createRefMiddleware(db);
+ * const writeProtection = createWriteProtectionMiddleware();
+ *
+ * app.use('/tenants/*', refMiddleware, writeProtection);
+ * ```
+ */
+declare const createWriteProtectionMiddleware: () => (c: Context, next: Next) => Promise<void>;
+/**
+ * @deprecated Use createRefMiddleware instead. This is kept for backwards compatibility.
+ */
+declare const refMiddlewareFactory: (db: AgentsManageDatabaseClient, options?: RefMiddlewareOptions) => (c: Context, next: Next) => Promise<void>;
+/**
+ * @deprecated Use createWriteProtectionMiddleware instead. This is kept for backwards compatibility.
+ */
+declare const writeProtectionMiddlewareFactory: () => (c: Context, next: Next) => Promise<void>;
+//#endregion
+export { RefContext, RefMiddlewareOptions, createRefMiddleware, createWriteProtectionMiddleware, refMiddlewareFactory, writeProtectionMiddlewareFactory };

package/dist/dolt/ref-middleware.js

@@ -0,0 +1,217 @@
+import { getLogger } from "../utils/logger.js";
+import { createApiError } from "../utils/error.js";
+import { isRefWritable, resolveRef } from "./ref-helpers.js";
+import { ensureBranchExists } from "./branch.js";
+
+//#region src/dolt/ref-middleware.ts
+const logger = getLogger("ref-middleware");
+/**
+* Default tenant ID extractor - extracts from /tenants/{tenantId} path pattern
+*/
+const defaultExtractTenantId = (c) => {
+	return c.req.path.match(/^\/tenants\/([^/]+)/)?.[1];
+};
+/**
+* Default project ID extractor - extracts from /tenants/{tenantId}/projects/{projectId} or
+* /tenants/{tenantId}/project-full/{projectId} path patterns
+*/
+const defaultExtractProjectId = (c) => {
+	return c.req.path.match(/^\/tenants\/[^/]+\/(?:projects|project-full)(?:\/([^/]+))?/)?.[1];
+};
+/**
+* Creates a ref resolution middleware factory.
+*
+* This middleware:
+* 1. Extracts tenantId and projectId from the request
+* 2. Resolves the `ref` query parameter to a ResolvedRef
+* 3. Creates branches if needed (tenant_main, project_main)
+* 4. Sets `resolvedRef` in the Hono context for downstream handlers
+*
+* @param db - The Doltgres database client to use for ref resolution
+* @param options - Optional configuration for extraction and validation
+* @returns Hono middleware function
+*
+* @example
+* ```typescript
+* import { createRefMiddleware } from '@inkeep/agents-core';
+* import { manageDbClient } from './db';
+*
+* const refMiddleware = createRefMiddleware(manageDbClient);
+* app.use('/tenants/*', refMiddleware);
+* ```
+*/
+const createRefMiddleware = (db, options = {}) => {
+	const { extractTenantId = defaultExtractTenantId, extractProjectId = defaultExtractProjectId, allowProjectIdFromBody = true } = options;
+	return async (c, next) => {
+		const ref = c.req.query("ref");
+		const pathSplit = c.req.path.split("/");
+		const tenantId = extractTenantId(c);
+		let projectId = extractProjectId(c);
+		if (!projectId && allowProjectIdFromBody && [
+			"POST",
+			"PUT",
+			"PATCH"
+		].includes(c.req.method)) try {
+			const body = await c.req.json();
+			if (body && typeof body.projectId === "string") {
+				projectId = body.projectId;
+				logger.debug({ projectId }, "Extracted projectId from request body");
+			}
+		} catch {
+			logger.debug({}, "Could not extract projectId from body");
+		}
+		if (!tenantId) throw createApiError({
+			code: "bad_request",
+			message: "Missing tenantId"
+		});
+		if (process.env.ENVIRONMENT === "test") {
+			const defaultRef = {
+				type: "branch",
+				name: projectId ? `${tenantId}_${projectId}_main` : `${tenantId}_main`,
+				hash: "test-hash"
+			};
+			c.set("resolvedRef", defaultRef);
+			await next();
+			return;
+		}
+		if (pathSplit.length < 4 && ref !== "main" && ref !== void 0) throw createApiError({
+			code: "bad_request",
+			message: "Ref is not supported for this path"
+		});
+		let resolvedRef;
+		if (projectId) resolvedRef = await resolveProjectRef(db, c, tenantId, projectId, ref);
+		else resolvedRef = await resolveTenantRef(db, tenantId, ref);
+		logger.info({
+			resolvedRef,
+			projectId,
+			tenantId
+		}, "Resolved ref");
+		c.set("resolvedRef", resolvedRef);
+		await next();
+	};
+};
+/**
+* Resolve ref for project-scoped requests
+*/
+async function resolveProjectRef(db, c, tenantId, projectId, ref) {
+	const projectMain = `${tenantId}_${projectId}_main`;
+	const projectScopedRef = `${tenantId}_${projectId}_${ref}`;
+	if (ref && ref !== "main") {
+		let refResult$1 = await resolveRef(db)(projectScopedRef);
+		if (!refResult$1) refResult$1 = await resolveRef(db)(ref);
+		if (!refResult$1) throw createApiError({
+			code: "not_found",
+			message: `Unknown ref: ${ref}`
+		});
+		return refResult$1;
+	}
+	let refResult = null;
+	try {
+		refResult = await resolveRef(db)(projectMain);
+	} catch (error) {
+		logger.warn({
+			error,
+			projectMain
+		}, "Failed to resolve project main branch");
+		refResult = null;
+	}
+	if (!refResult) {
+		if (c.req.method === "PUT") {
+			const tenantMain = `${tenantId}_main`;
+			let tenantRefResult = await resolveRef(db)(tenantMain);
+			if (!tenantRefResult) {
+				await ensureBranchExists(db, tenantMain);
+				tenantRefResult = await resolveRef(db)(tenantMain);
+			}
+			if (tenantRefResult) return tenantRefResult;
+			throw createApiError({
+				code: "internal_server_error",
+				message: `Failed to create tenant main branch for upsert`
+			});
+		}
+		throw createApiError({
+			code: "not_found",
+			message: `Project not found: ${projectId}`
+		});
+	}
+	return refResult;
+}
+/**
+* Resolve ref for tenant-level requests
+*/
+async function resolveTenantRef(db, tenantId, ref) {
+	const tenantMain = `${tenantId}_main`;
+	if (ref && ref !== "main") {
+		const tenantScopedRef = `${tenantId}_${ref}`;
+		let refResult$1 = await resolveRef(db)(tenantScopedRef);
+		if (!refResult$1) refResult$1 = await resolveRef(db)(ref);
+		if (!refResult$1) throw createApiError({
+			code: "not_found",
+			message: `Unknown ref: ${ref}`
+		});
+		return refResult$1;
+	}
+	let refResult = await resolveRef(db)(tenantMain);
+	if (!refResult) {
+		await ensureBranchExists(db, tenantMain);
+		refResult = await resolveRef(db)(tenantMain);
+		if (!refResult) throw createApiError({
+			code: "internal_server_error",
+			message: `Failed to create tenant main branch: ${tenantMain}`
+		});
+	}
+	return refResult;
+}
+/**
+* Creates a write protection middleware that prevents write operations on immutable refs.
+*
+* This middleware checks if the resolved ref is writable (branches are writable,
+* tags and commits are not) and rejects write operations on immutable refs.
+*
+* @returns Hono middleware function
+*
+* @example
+* ```typescript
+* import { createRefMiddleware, createWriteProtectionMiddleware } from '@inkeep/agents-core';
+*
+* const refMiddleware = createRefMiddleware(db);
+* const writeProtection = createWriteProtectionMiddleware();
+*
+* app.use('/tenants/*', refMiddleware, writeProtection);
+* ```
+*/
+const createWriteProtectionMiddleware = () => {
+	return async (c, next) => {
+		if (process.env.ENVIRONMENT === "test") {
+			await next();
+			return;
+		}
+		const resolvedRef = c.get("resolvedRef");
+		if (!resolvedRef) {
+			await next();
+			return;
+		}
+		const method = c.req.method;
+		if ([
+			"POST",
+			"PUT",
+			"PATCH",
+			"DELETE"
+		].includes(method) && !isRefWritable(resolvedRef)) throw createApiError({
+			code: "bad_request",
+			message: `Cannot perform write operation on ${resolvedRef.type}. Tags and commits are immutable. Write to a branch instead.`
+		});
+		await next();
+	};
+};
+/**
+* @deprecated Use createRefMiddleware instead. This is kept for backwards compatibility.
+*/
+const refMiddlewareFactory = createRefMiddleware;
+/**
+* @deprecated Use createWriteProtectionMiddleware instead. This is kept for backwards compatibility.
+*/
+const writeProtectionMiddlewareFactory = createWriteProtectionMiddleware;
+
+//#endregion
+export { createRefMiddleware, createWriteProtectionMiddleware, refMiddlewareFactory, writeProtectionMiddlewareFactory };