@inkeep/agents-core 0.41.2 → 0.42.0

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

@@ -0,0 +1,101 @@
+import { ResolvedRef } from "../validation/dolt-schemas.js";
+import { AgentsManageDatabaseClient } from "../db/manage/manage-client.js";
+import { Pool } from "pg";
+
+//#region src/dolt/ref-scope.d.ts
+
+/**
+ * Context stored in AsyncLocalStorage to detect nested withRef calls
+ */
+interface RefScopeContext {
+  db: AgentsManageDatabaseClient;
+  ref: string;
+  connectionId: string;
+}
+/**
+ * Error thrown when nested withRef calls are detected with different refs
+ */
+declare class NestedRefScopeError extends Error {
+  constructor(existingRef: string, attemptedRef: string);
+}
+/**
+ * Options for withRef function
+ */
+interface WithRefOptions {
+  /**
+   * Whether to auto-commit changes after successful callback execution.
+   * Only applies to branch refs (tags/commits are immutable).
+   * @default false
+   */
+  commit?: boolean;
+  /**
+   * Commit message to use when committing changes.
+   * @default 'withRef auto-commit'
+   */
+  commitMessage?: string;
+  /**
+   * Author information for the commit.
+   * @default { name: 'agents-api', email: 'api@inkeep.com' }
+   */
+  author?: {
+    name: string;
+    email: string;
+  };
+}
+/**
+ * Execute a function with a database connection scoped to a specific ref (branch/tag/commit).
+ *
+ * This function:
+ * 1. Gets a dedicated connection from the pool
+ * 2. For branches: checks out the branch directly
+ * 3. For tags/commits: creates a temporary branch from the hash, then checks out
+ * 4. Executes the callback with a Drizzle client scoped to that connection
+ * 5. Optionally auto-commits changes on success (if commit: true)
+ * 6. Cleans up: checks out main, deletes temp branch if created, releases connection
+ *
+ * Important:
+ * - The callback should only perform database operations
+ * - Do NOT hold the connection while making external API calls
+ *
+ * @param pool - The PostgreSQL connection pool
+ * @param resolvedRef - The resolved ref (branch, tag, or commit)
+ * @param dataAccessFn - The function to execute with the scoped database client
+ * @param options - Optional configuration for commit behavior
+ * @returns The result of the callback function
+ *
+ * @example
+ * ```typescript
+ * // Simple read (no commit)
+ * const agent = await withRef(pool, resolvedRef, (db) =>
+ *   getAgent(db, agentId)
+ * );
+ *
+ * // Write with auto-commit
+ * await withRef(pool, resolvedRef, async (db) => {
+ *   await updateAgent(db, agentId, data);
+ * }, { commit: true, commitMessage: 'Update agent config' });
+ *
+ * // Batch multiple operations with commit
+ * const result = await withRef(pool, resolvedRef, async (db) => {
+ *   await createCredential(db, credData);
+ *   await updateTool(db, toolId, { credentialId });
+ *   return { success: true };
+ * }, { commit: true, author: { name: 'oauth', email: 'oauth@inkeep.com' } });
+ * ```
+ */
+declare function withRef<T>(pool: Pool, resolvedRef: ResolvedRef, dataAccessFn: (db: AgentsManageDatabaseClient) => Promise<T>, options?: WithRefOptions): Promise<T>;
+/**
+ * Check if currently inside a withRef scope
+ */
+declare function isInRefScope(): boolean;
+/**
+ * Get the current ref scope context if inside one
+ */
+declare function getCurrentRefScope(): RefScopeContext | undefined;
+/**
+ * Get the database client from the current ref scope.
+ * Throws if not inside a withRef scope.
+ */
+declare function getRefScopedDb(): AgentsManageDatabaseClient;
+//#endregion
+export { NestedRefScopeError, WithRefOptions, getCurrentRefScope, getRefScopedDb, isInRefScope, withRef };

package/dist/dolt/ref-scope.js

@@ -0,0 +1,231 @@
+import { manage_schema_exports } from "../db/manage/manage-schema.js";
+import { getLogger } from "../utils/logger.js";
+import { generateId } from "../utils/conversations.js";
+import { doltAddAndCommit, doltReset, doltStatus } from "./commit.js";
+import { checkoutBranch } from "./branches-api.js";
+import { drizzle } from "drizzle-orm/node-postgres";
+import { AsyncLocalStorage } from "node:async_hooks";
+
+//#region src/dolt/ref-scope.ts
+const logger = getLogger("ref-scope");
+/**
+* AsyncLocalStorage to track active ref scope and detect nesting
+*/
+const refScopeStorage = new AsyncLocalStorage();
+/**
+* Error thrown when nested withRef calls are detected with different refs
+*/
+var NestedRefScopeError = class extends Error {
+	constructor(existingRef, attemptedRef) {
+		super(`Nested withRef detected. Already in ref scope '${existingRef}', attempted to enter '${attemptedRef}'. Either reuse the existing db from the outer scope, or batch your operations in a single withRef call.`);
+		this.name = "NestedRefScopeError";
+	}
+};
+/**
+* Execute a function with a database connection scoped to a specific ref (branch/tag/commit).
+*
+* This function:
+* 1. Gets a dedicated connection from the pool
+* 2. For branches: checks out the branch directly
+* 3. For tags/commits: creates a temporary branch from the hash, then checks out
+* 4. Executes the callback with a Drizzle client scoped to that connection
+* 5. Optionally auto-commits changes on success (if commit: true)
+* 6. Cleans up: checks out main, deletes temp branch if created, releases connection
+*
+* Important:
+* - The callback should only perform database operations
+* - Do NOT hold the connection while making external API calls
+*
+* @param pool - The PostgreSQL connection pool
+* @param resolvedRef - The resolved ref (branch, tag, or commit)
+* @param dataAccessFn - The function to execute with the scoped database client
+* @param options - Optional configuration for commit behavior
+* @returns The result of the callback function
+*
+* @example
+* ```typescript
+* // Simple read (no commit)
+* const agent = await withRef(pool, resolvedRef, (db) =>
+*   getAgent(db, agentId)
+* );
+*
+* // Write with auto-commit
+* await withRef(pool, resolvedRef, async (db) => {
+*   await updateAgent(db, agentId, data);
+* }, { commit: true, commitMessage: 'Update agent config' });
+*
+* // Batch multiple operations with commit
+* const result = await withRef(pool, resolvedRef, async (db) => {
+*   await createCredential(db, credData);
+*   await updateTool(db, toolId, { credentialId });
+*   return { success: true };
+* }, { commit: true, author: { name: 'oauth', email: 'oauth@inkeep.com' } });
+* ```
+*/
+async function withRef(pool, resolvedRef, dataAccessFn, options) {
+	const { commit = false, commitMessage = "withRef auto-commit", author } = options ?? {};
+	const startTime = Date.now();
+	const connectionId = generateId();
+	const existingScope = refScopeStorage.getStore();
+	if (existingScope) {
+		if (existingScope.ref === resolvedRef.name) {
+			logger.debug({
+				ref: resolvedRef.name,
+				existingConnectionId: existingScope.connectionId
+			}, "Reusing existing ref scope");
+			return dataAccessFn(existingScope.db);
+		}
+		throw new NestedRefScopeError(existingScope.ref, resolvedRef.name);
+	}
+	if (process.env.ENVIRONMENT === "test") {
+		const connection$1 = await pool.connect();
+		try {
+			const db = drizzle(connection$1, { schema: manage_schema_exports });
+			return await refScopeStorage.run({
+				db,
+				ref: resolvedRef.name,
+				connectionId
+			}, () => dataAccessFn(db));
+		} finally {
+			connection$1.release();
+		}
+	}
+	logger.debug({
+		ref: resolvedRef.name,
+		refType: resolvedRef.type,
+		connectionId
+	}, "Acquiring connection for ref scope");
+	const connection = await pool.connect();
+	let tempBranch = null;
+	try {
+		const db = drizzle(connection, { schema: manage_schema_exports });
+		if (resolvedRef.type === "branch") {
+			logger.debug({
+				branch: resolvedRef.name,
+				connectionId
+			}, "Checking out branch");
+			await checkoutBranch(db)({
+				branchName: resolvedRef.name,
+				syncSchema: false
+			});
+		} else {
+			tempBranch = `temp_${resolvedRef.type}_${Date.now()}_${generateId()}`;
+			logger.debug({
+				tempBranch,
+				hash: resolvedRef.hash,
+				refType: resolvedRef.type,
+				connectionId
+			}, "Creating temporary branch from ref");
+			await connection.query(`SELECT DOLT_CHECKOUT('-b', $1, $2)`, [tempBranch, resolvedRef.hash]);
+		}
+		const result = await refScopeStorage.run({
+			db,
+			ref: resolvedRef.name,
+			connectionId
+		}, () => dataAccessFn(db));
+		if (commit && resolvedRef.type === "branch") try {
+			if ((await doltStatus(db)()).length > 0) {
+				logger.info({
+					branch: resolvedRef.name,
+					message: commitMessage,
+					connectionId
+				}, "Auto-committing changes");
+				await doltAddAndCommit(db)({
+					message: commitMessage,
+					author: author ?? {
+						name: "agents-api",
+						email: "api@inkeep.com"
+					}
+				});
+				logger.info({
+					branch: resolvedRef.name,
+					connectionId
+				}, "Successfully committed changes");
+			}
+		} catch (commitError) {
+			logger.error({
+				error: commitError,
+				branch: resolvedRef.name,
+				connectionId
+			}, "Failed to auto-commit changes");
+		}
+		logger.debug({
+			ref: resolvedRef.name,
+			duration: Date.now() - startTime,
+			connectionId
+		}, "Ref scope completed successfully");
+		return result;
+	} catch (error) {
+		if (commit && resolvedRef.type === "branch") try {
+			const db = drizzle(connection, { schema: manage_schema_exports });
+			if ((await doltStatus(db)()).length > 0) {
+				await doltReset(db)();
+				logger.info({
+					branch: resolvedRef.name,
+					connectionId
+				}, "Reset uncommitted changes due to failed operation");
+			}
+		} catch (resetError) {
+			logger.error({
+				error: resetError,
+				branch: resolvedRef.name,
+				connectionId
+			}, "Failed to reset changes after error");
+		}
+		logger.error({
+			ref: resolvedRef.name,
+			duration: Date.now() - startTime,
+			connectionId,
+			error
+		}, "Ref scope failed");
+		throw error;
+	} finally {
+		try {
+			await connection.query(`SELECT DOLT_CHECKOUT('main')`);
+			if (tempBranch) {
+				logger.debug({
+					tempBranch,
+					connectionId
+				}, "Deleting temporary branch");
+				await connection.query(`SELECT DOLT_BRANCH('-D', $1)`, [tempBranch]);
+			}
+		} catch (cleanupError) {
+			logger.error({
+				error: cleanupError,
+				tempBranch,
+				connectionId
+			}, "Error during ref scope cleanup");
+		} finally {
+			connection.release();
+			logger.debug({
+				ref: resolvedRef.name,
+				duration: Date.now() - startTime,
+				connectionId
+			}, "Connection released");
+		}
+	}
+}
+/**
+* Check if currently inside a withRef scope
+*/
+function isInRefScope() {
+	return refScopeStorage.getStore() !== void 0;
+}
+/**
+* Get the current ref scope context if inside one
+*/
+function getCurrentRefScope() {
+	return refScopeStorage.getStore();
+}
+/**
+* Get the database client from the current ref scope.
+* Throws if not inside a withRef scope.
+*/
+function getRefScopedDb() {
+	const scope = refScopeStorage.getStore();
+	if (!scope) throw new Error("Not inside a withRef scope. Wrap your code in withRef() to get a ref-scoped database client.");
+	return scope.db;
+}
+
+//#endregion
+export { NestedRefScopeError, getCurrentRefScope, getRefScopedDb, isInRefScope, withRef };

package/dist/dolt/schema-sync.d.ts

@@ -0,0 +1,134 @@
+import { AgentsManageDatabaseClient } from "../db/manage/manage-client.js";
+
+//#region src/dolt/schema-sync.d.ts
+
+/**
+ * The branch that serves as the source of truth for schema.
+ * All other branches sync their schema from this branch.
+ */
+declare const SCHEMA_SOURCE_BRANCH = "main";
+/**
+ * Represents a single schema difference between two branches.
+ * Each row represents a table that differs between the branches,
+ * showing the full CREATE TABLE statements for comparison.
+ */
+type SchemaDiff = {
+  /** Table name in the source branch (e.g., "public.agent") */
+  fromTableName: string;
+  /** Table name in the target branch (e.g., "public.agent") */
+  toTableName: string;
+  /** Full CREATE TABLE statement from the source branch */
+  fromCreateStatement: string;
+  /** Full CREATE TABLE statement from the target branch */
+  toCreateStatement: string;
+};
+/**
+ * Result of a schema sync operation
+ */
+type SchemaSyncResult = {
+  /** Whether a sync was performed */
+  synced: boolean;
+  /** Whether there were schema differences detected */
+  hadDifferences: boolean;
+  /** The schema differences that were found */
+  differences?: SchemaDiff[];
+  /** Error message if sync failed */
+  error?: string;
+  /** The merge commit hash if sync was successful */
+  mergeCommitHash?: string;
+  /** Whether sync was skipped because another request holds the lock */
+  skippedDueToLock?: boolean;
+};
+/**
+ * Options for schema sync operations
+ */
+type SchemaSyncOptions = {
+  /** Automatically commit pending changes before syncing */
+  autoCommitPending?: boolean;
+  /** Custom commit message for the schema sync */
+  commitMessage?: string;
+  /** Author information for the commit */
+  author?: {
+    name: string;
+    email: string;
+  };
+};
+/**
+ * Options for ensuring schema compatibility
+ */
+type EnsureSchemaSyncOptions = SchemaSyncOptions & {
+  /** Automatically sync schema if differences are found */
+  autoSync?: boolean;
+};
+/**
+ * Get the currently active branch
+ */
+declare const getActiveBranch: (db: AgentsManageDatabaseClient) => () => Promise<string>;
+/**
+ * Get schema differences between the schema source branch and a target branch.
+ * Returns an empty array if schemas are identical.
+ *
+ * The comparison is done as dolt_schema_diff(targetBranch, SCHEMA_SOURCE_BRANCH),
+ * so fromCreateStatement shows the target branch's schema and toCreateStatement
+ * shows main's schema (what we want to sync to).
+ *
+ * @param targetBranch - The branch to compare against the schema source
+ * @returns Array of schema differences (one per table that differs)
+ */
+declare const getSchemaDiff: (db: AgentsManageDatabaseClient) => (targetBranch: string) => Promise<SchemaDiff[]>;
+/**
+ * Check if a branch has schema differences from the schema source branch
+ */
+declare const hasSchemaDifferences: (db: AgentsManageDatabaseClient) => (targetBranch: string) => Promise<boolean>;
+/**
+ * Check if the current branch has uncommitted changes
+ */
+declare const hasUncommittedChanges: (db: AgentsManageDatabaseClient) => () => Promise<boolean>;
+/**
+ * Sync schema from the schema source branch (main) into the current branch.
+ * This performs a merge of the schema source branch into the current branch.
+ *
+ * Uses a non-blocking advisory lock to prevent duplicate syncs when multiple
+ * concurrent requests attempt to sync the same branch. If another request is
+ * already syncing, this function returns immediately with skippedDueToLock: true.
+ *
+ * Prerequisites:
+ * - Current branch must not have uncommitted changes (unless autoCommitPending is true)
+ * - Current branch must not be the schema source branch itself
+ *
+ * @param options - Sync options
+ * @returns Result of the sync operation
+ */
+declare const syncSchemaFromMain: (db: AgentsManageDatabaseClient) => (options?: SchemaSyncOptions) => Promise<SchemaSyncResult>;
+/**
+ * Ensure the current branch has schema in sync with the schema source branch.
+ * This is a convenience function for checking and optionally syncing schema.
+ *
+ * Use cases:
+ * - Call before write operations to ensure schema compatibility
+ * - Call before merge operations to prevent schema conflicts
+ * - Call on branch checkout to keep branches up-to-date
+ *
+ * @param options - Options for the check and optional sync
+ * @returns Result indicating current sync status
+ */
+declare const ensureSchemaSync: (db: AgentsManageDatabaseClient) => (options?: EnsureSchemaSyncOptions) => Promise<SchemaSyncResult>;
+/**
+ * Get a human-readable summary of schema differences
+ */
+declare const formatSchemaDiffSummary: (differences: SchemaDiff[]) => string;
+/**
+ * Check if two branches have compatible schemas (both are in sync with main).
+ * Useful before merging two feature branches.
+ *
+ * @param branchA - First branch to check
+ * @param branchB - Second branch to check
+ * @returns Object indicating if both branches are schema-compatible
+ */
+declare const areBranchesSchemaCompatible: (db: AgentsManageDatabaseClient) => (branchA: string, branchB: string) => Promise<{
+  compatible: boolean;
+  branchADifferences: SchemaDiff[];
+  branchBDifferences: SchemaDiff[];
+}>;
+//#endregion
+export { EnsureSchemaSyncOptions, SCHEMA_SOURCE_BRANCH, SchemaDiff, SchemaSyncOptions, SchemaSyncResult, areBranchesSchemaCompatible, ensureSchemaSync, formatSchemaDiffSummary, getActiveBranch, getSchemaDiff, hasSchemaDifferences, hasUncommittedChanges, syncSchemaFromMain };