@inkeep/agents-core 0.41.2 → 0.42.0

package/dist/dolt/merge.d.ts

@@ -0,0 +1,63 @@
+import { AgentsManageDatabaseClient } from "../db/manage/manage-client.js";
+
+//#region src/dolt/merge.d.ts
+
+/**
+ * Merge another branch into the current branch
+ * Returns merge status and handles conflicts by allowing commit with conflicts
+ */
+declare const doltMerge: (db: AgentsManageDatabaseClient) => (params: {
+  fromBranch: string;
+  toBranch: string;
+  message?: string;
+  noFastForward?: boolean;
+  author?: {
+    name: string;
+    email: string;
+  };
+}) => Promise<{
+  status: "success" | "conflicts";
+  from: string;
+  to: string;
+  toHead?: string;
+  hasConflicts: boolean;
+}>;
+/**
+ * Abort a merge
+ */
+declare const doltAbortMerge: (db: AgentsManageDatabaseClient) => () => Promise<void>;
+/**
+ * Get merge status
+ */
+declare const doltMergeStatus: (db: AgentsManageDatabaseClient) => () => Promise<{
+  isMerging: boolean;
+  source?: string;
+  target?: string;
+  unmergedTables?: string[];
+}>;
+/**
+ * Get list of tables with conflicts
+ */
+declare const doltConflicts: (db: AgentsManageDatabaseClient) => () => Promise<{
+  table: string;
+  numConflicts: number;
+}[]>;
+/**
+ * Get detailed conflicts for a specific table
+ */
+declare const doltTableConflicts: (db: AgentsManageDatabaseClient) => (params: {
+  tableName: string;
+}) => Promise<any[]>;
+/**
+ * Get schema conflicts
+ */
+declare const doltSchemaConflicts: (db: AgentsManageDatabaseClient) => () => Promise<any[]>;
+/**
+ * Resolve conflicts for a table using a strategy
+ */
+declare const doltResolveConflicts: (db: AgentsManageDatabaseClient) => (params: {
+  tableName: string;
+  strategy: "ours" | "theirs";
+}) => Promise<void>;
+//#endregion
+export { doltAbortMerge, doltConflicts, doltMerge, doltMergeStatus, doltResolveConflicts, doltSchemaConflicts, doltTableConflicts };

package/dist/dolt/merge.js

@@ -0,0 +1,81 @@
+import { doltCheckout } from "./branch.js";
+import { sql } from "drizzle-orm";
+
+//#region src/dolt/merge.ts
+/**
+* Merge another branch into the current branch
+* Returns merge status and handles conflicts by allowing commit with conflicts
+*/
+const doltMerge = (db) => async (params) => {
+	console.log("merging branch", params.fromBranch, "into", params.toBranch);
+	await doltCheckout(db)({ branch: params.toBranch });
+	const toHead = (await db.execute(sql`SELECT HASHOF('HEAD') as hash`)).rows[0]?.hash;
+	const args = [`'${params.fromBranch}'`];
+	if (params.noFastForward) args.push("'--no-ff'");
+	if (params.message) args.push("'-m'", `'${params.message.replace(/'/g, "''")}'`);
+	if (params.author) args.push("'--author'", `'${params.author.name} <${params.author.email}>'`);
+	const firstRow = (await db.execute(sql.raw(`SELECT DOLT_MERGE(${args.join(", ")})`))).rows[0] ?? {};
+	const mergeResult = typeof firstRow.conflicts === "number" || typeof firstRow.conflicts === "string" || firstRow.conflicts == null ? firstRow : Object.values(firstRow)[0] ?? {};
+	const conflicts = Number(mergeResult.conflicts ?? 0);
+	if (Number.isFinite(conflicts) && conflicts > 0) return {
+		status: "conflicts",
+		from: params.fromBranch,
+		to: params.toBranch,
+		toHead,
+		hasConflicts: true
+	};
+	return {
+		status: "success",
+		from: params.fromBranch,
+		to: params.toBranch,
+		toHead,
+		hasConflicts: false
+	};
+};
+/**
+* Abort a merge
+*/
+const doltAbortMerge = (db) => async () => {
+	await db.execute(sql.raw(`SELECT DOLT_MERGE('--abort')`));
+};
+/**
+* Get merge status
+*/
+const doltMergeStatus = (db) => async () => {
+	const status = (await db.execute(sql`SELECT * FROM DOLT_MERGE_STATUS`)).rows[0];
+	if (!status || !status.is_merging) return { isMerging: false };
+	return {
+		isMerging: status.is_merging,
+		source: status.source,
+		target: status.target,
+		unmergedTables: status.unmerged_tables ? status.unmerged_tables.split(",") : []
+	};
+};
+/**
+* Get list of tables with conflicts
+*/
+const doltConflicts = (db) => async () => {
+	return (await db.execute(sql`SELECT * FROM dolt_conflicts`)).rows;
+};
+/**
+* Get detailed conflicts for a specific table
+*/
+const doltTableConflicts = (db) => async (params) => {
+	return (await db.execute(sql.raw(`SELECT * FROM dolt_conflicts_${params.tableName}`))).rows;
+};
+/**
+* Get schema conflicts
+*/
+const doltSchemaConflicts = (db) => async () => {
+	return (await db.execute(sql`SELECT * FROM dolt_schema_conflicts`)).rows;
+};
+/**
+* Resolve conflicts for a table using a strategy
+*/
+const doltResolveConflicts = (db) => async (params) => {
+	await db.execute(sql`SET dolt_allow_commit_conflicts = 1`);
+	await db.execute(sql.raw(`SELECT DOLT_CONFLICTS_RESOLVE('--${params.strategy}', '${params.tableName}')`));
+};
+
+//#endregion
+export { doltAbortMerge, doltConflicts, doltMerge, doltMergeStatus, doltResolveConflicts, doltSchemaConflicts, doltTableConflicts };

package/dist/dolt/migrate-all-branches.d.ts

@@ -0,0 +1,4 @@
+//#region src/dolt/migrate-all-branches.d.ts
+declare const main: () => Promise<void>;
+//#endregion
+export { main };

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

@@ -0,0 +1,78 @@
+import { createAgentsManageDatabaseClient } from "../db/manage/manage-client.js";
+import { syncSchemaFromMain } from "./schema-sync.js";
+import { doltCheckout, doltListBranches } from "./branch.js";
+
+//#region src/dolt/migrate-all-branches.ts
+const ansi = {
+	reset: "\x1B[0m",
+	dim: "\x1B[2m",
+	bold: "\x1B[1m",
+	green: "\x1B[32m",
+	red: "\x1B[31m",
+	yellow: "\x1B[33m",
+	cyan: "\x1B[36m"
+};
+const format = {
+	header: (text) => `${ansi.bold}${ansi.cyan}${text}${ansi.reset}`,
+	ok: (text) => `${ansi.green}${text}${ansi.reset}`,
+	warn: (text) => `${ansi.yellow}${text}${ansi.reset}`,
+	err: (text) => `${ansi.red}${text}${ansi.reset}`,
+	dim: (text) => `${ansi.dim}${text}${ansi.reset}`,
+	bold: (text) => `${ansi.bold}${text}${ansi.reset}`
+};
+const ms = (start, end) => `${Math.max(0, end - start)}ms`;
+const main = async () => {
+	const startedAt = Date.now();
+	const db = createAgentsManageDatabaseClient({});
+	const branches = await doltListBranches(db)();
+	const targetBranches = branches.filter((b) => b.name !== "main");
+	const nameWidth = Math.max(12, ...targetBranches.map((b) => b.name.length));
+	console.log(format.header(`Sync schema from main → ${targetBranches.length} branches`));
+	console.log(format.dim(`Started: ${(/* @__PURE__ */ new Date()).toISOString()}`));
+	console.log("");
+	let syncedCount = 0;
+	let upToDateCount = 0;
+	let errorCount = 0;
+	for (const branch of branches) {
+		if (branch.name === "main") continue;
+		const branchStartedAt = Date.now();
+		const paddedName = branch.name.padEnd(nameWidth, " ");
+		console.log(`${format.bold("─".repeat(Math.min(80, nameWidth + 34)))}`);
+		console.log(`${format.bold("Branch")}  ${format.header(paddedName)}`);
+		try {
+			process.stdout.write(`${format.dim("Action ")}  checkout… `);
+			await doltCheckout(db)({ branch: branch.name });
+			console.log(format.ok("[OK]"));
+			process.stdout.write(`${format.dim("Action ")}  sync schema… `);
+			const result = await syncSchemaFromMain(db)();
+			if (result.synced) {
+				syncedCount += 1;
+				console.log(format.ok("[SYNCED]"));
+				console.log(`${format.dim("Result ")}  ${format.ok("Schema updated")} ${format.dim(`(${ms(branchStartedAt, Date.now())})`)}`);
+			} else if (result.error) {
+				errorCount += 1;
+				console.log(format.err("[FAILED]"));
+				console.log(`${format.dim("Result ")}  ${format.err("Error")} ${format.dim(`(${ms(branchStartedAt, Date.now())})`)}`);
+				console.log(`${format.dim("Details")}  ${result.error}`);
+			} else {
+				upToDateCount += 1;
+				console.log(format.warn("[NOOP]"));
+				console.log(`${format.dim("Result ")}  ${format.warn("Already up to date")} ${format.dim(`(${ms(branchStartedAt, Date.now())})`)}`);
+			}
+		} catch (error) {
+			errorCount += 1;
+			console.log(format.err("[FAILED]"));
+			const message = error instanceof Error ? error.message : String(error);
+			console.log(`${format.dim("Result ")}  ${format.err("Error")} ${format.dim(`(${ms(branchStartedAt, Date.now())})`)}`);
+			console.log(`${format.dim("Details")}  ${message}`);
+		}
+		console.log("");
+	}
+	console.log(format.bold("─".repeat(80)));
+	console.log(`${format.bold("Summary")}  ${format.ok(`${syncedCount} synced`)}, ${format.warn(`${upToDateCount} up to date`)}, ${errorCount > 0 ? format.err(`${errorCount} failed`) : format.ok("0 failed")}`);
+	console.log(format.dim(`Total: ${ms(startedAt, Date.now())}`));
+};
+main();
+
+//#endregion
+export { main };

package/dist/dolt/migrate-dolt.d.ts

@@ -0,0 +1 @@
+export { };

package/dist/dolt/migrate-dolt.js

@@ -0,0 +1,22 @@
+import { loadEnvironmentFiles } from "../env.js";
+import { createAgentsManageDatabaseClient } from "../db/manage/manage-client.js";
+import { doltAddAndCommit, doltStatus } from "./commit.js";
+import { execSync } from "node:child_process";
+
+//#region src/dolt/migrate-dolt.ts
+const commitMigrations = async () => {
+	loadEnvironmentFiles();
+	try {
+		execSync("drizzle-kit migrate --config=drizzle.manage.config.ts", { stdio: "inherit" });
+	} catch (error) {
+		console.error("❌ Error running migrations:", error);
+		process.exit(1);
+	}
+	const db = createAgentsManageDatabaseClient({ connectionString: process.env.INKEEP_AGENTS_MANAGE_DATABASE_URL });
+	if ((await doltStatus(db)()).length > 0) await doltAddAndCommit(db)({ message: "Applied database migrations" });
+	else console.log("ℹ️  No changes to commit - database is up to date\n");
+};
+commitMigrations();
+
+//#endregion
+export {  };

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

@@ -0,0 +1,19 @@
+import { ResolvedRef } from "../validation/dolt-schemas.js";
+import { AgentsManageDatabaseClient } from "../db/manage/manage-client.js";
+
+//#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>;
+declare const getCurrentBranchOrCommit: (db: AgentsManageDatabaseClient) => () => Promise<{
+  ref: string;
+  hash: string;
+  type: RefType;
+}>;
+declare const getProjectMainResolvedRef: (db: AgentsManageDatabaseClient) => (tenantId: string, projectId: string) => Promise<ResolvedRef>;
+//#endregion
+export { RefType, checkoutRef, getCurrentBranchOrCommit, getProjectMainResolvedRef, getProjectScopedRef, getTenantScopedRef, isRefWritable, isValidCommitHash, resolveRef };

package/dist/dolt/ref-helpers.js

@@ -0,0 +1,65 @@
+import { doltHashOf, doltListTags } from "./commit.js";
+import { checkoutBranch } from "./branches-api.js";
+import { doltListBranches } from "./branch.js";
+import { sql } from "drizzle-orm";
+
+//#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",
+		name: ref,
+		hash: ref
+	};
+	const tag = (await doltListTags(db)()).find((t) => t.tag_name === ref);
+	if (tag) return {
+		type: "tag",
+		name: ref,
+		hash: tag.tag_hash
+	};
+	const branch = (await doltListBranches(db)()).find((b) => b.name === ref);
+	if (branch) return {
+		type: "branch",
+		name: ref,
+		hash: branch.hash
+	};
+	return null;
+};
+const isRefWritable = (resolvedRef) => {
+	return resolvedRef.type === "branch";
+};
+const checkoutRef = (db) => async (resolvedRef) => {
+	if (resolvedRef.type === "branch") await checkoutBranch(db)({ branchName: resolvedRef.name });
+	else await db.execute(sql.raw(`SELECT DOLT_CHECKOUT('${resolvedRef.hash}')`));
+};
+const getCurrentBranchOrCommit = (db) => async () => {
+	const branch = (await db.execute(sql`SELECT ACTIVE_BRANCH() as branch`)).rows[0]?.branch;
+	if (branch) return {
+		ref: branch,
+		hash: await doltHashOf(db)({ revision: branch }),
+		type: "branch"
+	};
+	const hash = (await db.execute(sql`SELECT DOLT_HASHOF('HEAD') as hash`)).rows[0]?.hash;
+	return {
+		ref: hash,
+		hash,
+		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, 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 };