@lleverage-ai/agent-sdk 0.0.1

package/dist/backends/composite.d.ts

@@ -0,0 +1,258 @@
+/**
+ * Composite backend that routes operations to different backends based on path prefixes.
+ *
+ * CompositeBackend allows you to combine multiple backends, routing operations to
+ * the appropriate backend based on the file path. This enables scenarios like:
+ * - Memory files from a StateBackend
+ * - Persistent files from a PersistentBackend
+ * - Real filesystem access for specific directories
+ *
+ * @example
+ * ```typescript
+ * const state = createAgentState();
+ * const backend = new CompositeBackend(
+ *   new StateBackend(state),  // Default for unmatched paths
+ *   {
+ *     '/memories/': new PersistentBackend({ store }),
+ *     '/workspace/': new FilesystemBackend({ rootDir: './workspace' }),
+ *   }
+ * );
+ *
+ * // Routes to PersistentBackend
+ * await backend.write('/memories/user-prefs.json', '{}');
+ *
+ * // Routes to FilesystemBackend
+ * await backend.read('/workspace/src/index.ts');
+ *
+ * // Routes to StateBackend (default)
+ * await backend.write('/scratch/notes.txt', 'temp notes');
+ * ```
+ *
+ * @packageDocumentation
+ */
+import type { BackendProtocol, EditResult, FileData, FileInfo, GrepMatch, WriteResult } from "../backend.js";
+/**
+ * Configuration for routing paths to backends.
+ *
+ * Keys are path prefixes (should start with '/' and optionally end with '/').
+ * Values are the backends that handle those paths.
+ *
+ * @example
+ * ```typescript
+ * const routes: RouteConfig = {
+ *   '/memories/': persistentBackend,
+ *   '/cache/': stateBackend,
+ *   '/project/': filesystemBackend,
+ * };
+ * ```
+ *
+ * @category Backend
+ */
+export type RouteConfig = Record<string, BackendProtocol>;
+/**
+ * Options for creating a CompositeBackend.
+ *
+ * @category Backend
+ */
+export interface CompositeBackendOptions {
+    /**
+     * The default backend for paths that don't match any route.
+     */
+    defaultBackend: BackendProtocol;
+    /**
+     * Route configuration mapping path prefixes to backends.
+     */
+    routes: RouteConfig;
+}
+/**
+ * A backend that routes operations to different backends based on path prefixes.
+ *
+ * Routes are matched by longest-prefix first. For example, if you have routes for
+ * `/memories/` and `/memories/archived/`, a path like `/memories/archived/old.txt`
+ * will route to the `/memories/archived/` backend.
+ *
+ * For aggregate operations (glob, grep), results are collected from all backends
+ * and merged together.
+ *
+ * @example
+ * ```typescript
+ * const backend = new CompositeBackend(
+ *   new StateBackend(state),
+ *   {
+ *     '/memories/': new PersistentBackend({ store }),
+ *     '/project/': new FilesystemBackend({ rootDir: './project' }),
+ *   }
+ * );
+ *
+ * // Write to different backends based on path
+ * await backend.write('/memories/notes.md', '# Notes');  // PersistentBackend
+ * await backend.write('/project/src/app.ts', '...');     // FilesystemBackend
+ * await backend.write('/temp/scratch.txt', '...');       // StateBackend (default)
+ *
+ * // Glob across all backends
+ * const allFiles = await backend.globInfo('**\/*.ts');
+ * ```
+ *
+ * @category Backend
+ */
+export declare class CompositeBackend implements BackendProtocol {
+    private readonly defaultBackend;
+    private readonly routes;
+    /**
+     * Create a new CompositeBackend.
+     *
+     * @param defaultBackend - Backend for paths that don't match any route
+     * @param routes - Map of path prefixes to backends
+     */
+    constructor(defaultBackend: BackendProtocol, routes: RouteConfig);
+    /**
+     * List files and directories at the given path.
+     *
+     * Routes to the appropriate backend based on path prefix.
+     *
+     * @param path - Directory path to list
+     * @returns Array of file/directory info
+     */
+    lsInfo(path: string): Promise<FileInfo[]>;
+    /**
+     * Read file content with optional line numbers.
+     *
+     * @param filePath - Path to the file to read
+     * @param offset - Starting line offset (0-indexed)
+     * @param limit - Maximum number of lines to read
+     * @returns Formatted content with line numbers
+     */
+    read(filePath: string, offset?: number, limit?: number): Promise<string>;
+    /**
+     * Read raw file content as FileData.
+     *
+     * @param filePath - Path to the file to read
+     * @returns Raw file data with content and timestamps
+     */
+    readRaw(filePath: string): Promise<FileData>;
+    /**
+     * Search for pattern matches using regex across all backends.
+     *
+     * Results are aggregated from all backends. Each backend's grep
+     * is limited to its own path scope.
+     *
+     * @param pattern - Regular expression pattern to search for
+     * @param path - Directory to search in (defaults to root)
+     * @param glob - Glob pattern to filter files
+     * @returns Array of matches from all backends
+     */
+    grepRaw(pattern: string, path?: string | null, glob?: string | null): Promise<GrepMatch[]>;
+    /**
+     * Find files matching a glob pattern across all backends.
+     *
+     * Results are aggregated from all backends that could contain
+     * matching files.
+     *
+     * @param pattern - Glob pattern
+     * @param path - Base directory for the search
+     * @returns Array of matching file info from all backends
+     */
+    globInfo(pattern: string, path?: string): Promise<FileInfo[]>;
+    /**
+     * Create or overwrite a file.
+     *
+     * Routes to the appropriate backend based on path prefix.
+     *
+     * @param filePath - Path for the new file
+     * @param content - Content to write
+     * @returns Result indicating success or failure
+     */
+    write(filePath: string, content: string): Promise<WriteResult>;
+    /**
+     * Edit a file by replacing text.
+     *
+     * Routes to the appropriate backend based on path prefix.
+     *
+     * @param filePath - Path to the file to edit
+     * @param oldString - Text to find and replace
+     * @param newString - Replacement text
+     * @param replaceAll - If true, replace all occurrences
+     * @returns Result indicating success or failure
+     */
+    edit(filePath: string, oldString: string, newString: string, replaceAll?: boolean): Promise<EditResult>;
+    /**
+     * Get the backend that handles a specific path.
+     *
+     * Useful for debugging or when you need direct access to a specific backend.
+     *
+     * @param path - Path to check
+     * @returns The backend that handles this path
+     */
+    getBackendForPath(path: string): BackendProtocol;
+    /**
+     * Get all configured routes.
+     *
+     * @returns Array of route configurations sorted by prefix length (longest first)
+     */
+    getRoutes(): Array<{
+        prefix: string;
+        backend: BackendProtocol;
+    }>;
+    /**
+     * Get the default backend.
+     *
+     * @returns The default backend for unmatched paths
+     */
+    getDefaultBackend(): BackendProtocol;
+    /**
+     * Normalize a route prefix.
+     * @internal
+     */
+    private normalizePrefix;
+    /**
+     * Normalize a path.
+     * @internal
+     */
+    private normalizePath;
+    /**
+     * Find the matching route for a path using longest-prefix matching.
+     * @internal
+     */
+    private findMatchingRoute;
+    /**
+     * Resolve which backend handles a path and return the relative path.
+     * @internal
+     */
+    private resolveBackend;
+    /**
+     * Convert a composite path to a relative path for the backend.
+     * @internal
+     */
+    private toRelativePath;
+    /**
+     * Convert a backend-relative path to a composite path.
+     * @internal
+     */
+    private toCompositePath;
+    /**
+     * Check if parentPath is a parent of (or equal to) childPath.
+     * @internal
+     */
+    private isParentPath;
+}
+/**
+ * Create a CompositeBackend from options.
+ *
+ * @param options - Configuration options
+ * @returns A new CompositeBackend
+ *
+ * @example
+ * ```typescript
+ * const backend = createCompositeBackend({
+ *   defaultBackend: new StateBackend(state),
+ *   routes: {
+ *     '/memories/': persistentBackend,
+ *     '/workspace/': filesystemBackend,
+ *   },
+ * });
+ * ```
+ *
+ * @category Backend
+ */
+export declare function createCompositeBackend(options: CompositeBackendOptions): CompositeBackend;
+//# sourceMappingURL=composite.d.ts.map

package/dist/backends/composite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composite.d.ts","sourceRoot":"","sources":["../../src/backends/composite.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EACV,eAAe,EACf,UAAU,EACV,QAAQ,EACR,QAAQ,EACR,SAAS,EACT,WAAW,EACZ,MAAM,eAAe,CAAC;AAMvB;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;AAE1D;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC;;OAEG;IACH,cAAc,EAAE,eAAe,CAAC;IAEhC;;OAEG;IACH,MAAM,EAAE,WAAW,CAAC;CACrB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAAa,gBAAiB,YAAW,eAAe;IACtD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAkB;IACjD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsD;IAE7E;;;;;OAKG;gBACS,cAAc,EAAE,eAAe,EAAE,MAAM,EAAE,WAAW;IAYhE;;;;;;;OAOG;IACG,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAgB/C;;;;;;;OAOG;IACG,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAK9E;;;;;OAKG;IACG,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAKlD;;;;;;;;;;OAUG;IACG,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAyDhG;;;;;;;;;OASG;IACG,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAoDnE;;;;;;;;OAQG;IACG,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAepE;;;;;;;;;;OAUG;IACG,IAAI,CACR,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,UAAU,CAAC,EAAE,OAAO,GACnB,OAAO,CAAC,UAAU,CAAC;IAmBtB;;;;;;;OAOG;IACH,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe;IAIhD;;;;OAIG;IACH,SAAS,IAAI,KAAK,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,eAAe,CAAA;KAAE,CAAC;IAIhE;;;;OAIG;IACH,iBAAiB,IAAI,eAAe;IAQpC;;;OAGG;IACH,OAAO,CAAC,eAAe;IAQvB;;;OAGG;IACH,OAAO,CAAC,aAAa;IAOrB;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAiBzB;;;OAGG;IACH,OAAO,CAAC,cAAc;IAmBtB;;;OAGG;IACH,OAAO,CAAC,cAAc;IAkBtB;;;OAGG;IACH,OAAO,CAAC,eAAe;IAavB;;;OAGG;IACH,OAAO,CAAC,YAAY;CAgBrB;AAMD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,uBAAuB,GAAG,gBAAgB,CAEzF"}

package/dist/backends/composite.js

@@ -0,0 +1,437 @@
+/**
+ * Composite backend that routes operations to different backends based on path prefixes.
+ *
+ * CompositeBackend allows you to combine multiple backends, routing operations to
+ * the appropriate backend based on the file path. This enables scenarios like:
+ * - Memory files from a StateBackend
+ * - Persistent files from a PersistentBackend
+ * - Real filesystem access for specific directories
+ *
+ * @example
+ * ```typescript
+ * const state = createAgentState();
+ * const backend = new CompositeBackend(
+ *   new StateBackend(state),  // Default for unmatched paths
+ *   {
+ *     '/memories/': new PersistentBackend({ store }),
+ *     '/workspace/': new FilesystemBackend({ rootDir: './workspace' }),
+ *   }
+ * );
+ *
+ * // Routes to PersistentBackend
+ * await backend.write('/memories/user-prefs.json', '{}');
+ *
+ * // Routes to FilesystemBackend
+ * await backend.read('/workspace/src/index.ts');
+ *
+ * // Routes to StateBackend (default)
+ * await backend.write('/scratch/notes.txt', 'temp notes');
+ * ```
+ *
+ * @packageDocumentation
+ */
+// =============================================================================
+// Composite Backend Implementation
+// =============================================================================
+/**
+ * A backend that routes operations to different backends based on path prefixes.
+ *
+ * Routes are matched by longest-prefix first. For example, if you have routes for
+ * `/memories/` and `/memories/archived/`, a path like `/memories/archived/old.txt`
+ * will route to the `/memories/archived/` backend.
+ *
+ * For aggregate operations (glob, grep), results are collected from all backends
+ * and merged together.
+ *
+ * @example
+ * ```typescript
+ * const backend = new CompositeBackend(
+ *   new StateBackend(state),
+ *   {
+ *     '/memories/': new PersistentBackend({ store }),
+ *     '/project/': new FilesystemBackend({ rootDir: './project' }),
+ *   }
+ * );
+ *
+ * // Write to different backends based on path
+ * await backend.write('/memories/notes.md', '# Notes');  // PersistentBackend
+ * await backend.write('/project/src/app.ts', '...');     // FilesystemBackend
+ * await backend.write('/temp/scratch.txt', '...');       // StateBackend (default)
+ *
+ * // Glob across all backends
+ * const allFiles = await backend.globInfo('**\/*.ts');
+ * ```
+ *
+ * @category Backend
+ */
+export class CompositeBackend {
+    defaultBackend;
+    routes;
+    /**
+     * Create a new CompositeBackend.
+     *
+     * @param defaultBackend - Backend for paths that don't match any route
+     * @param routes - Map of path prefixes to backends
+     */
+    constructor(defaultBackend, routes) {
+        this.defaultBackend = defaultBackend;
+        // Sort routes by prefix length descending for longest-prefix matching
+        this.routes = Object.entries(routes)
+            .map(([prefix, backend]) => ({
+            prefix: this.normalizePrefix(prefix),
+            backend,
+        }))
+            .sort((a, b) => b.prefix.length - a.prefix.length);
+    }
+    /**
+     * List files and directories at the given path.
+     *
+     * Routes to the appropriate backend based on path prefix.
+     *
+     * @param path - Directory path to list
+     * @returns Array of file/directory info
+     */
+    async lsInfo(path) {
+        const { backend, relativePath } = this.resolveBackend(path);
+        const results = await backend.lsInfo(relativePath);
+        // Map paths back to composite paths
+        const route = this.findMatchingRoute(path);
+        if (route) {
+            return results.map((info) => ({
+                ...info,
+                path: this.toCompositePath(info.path, route.prefix),
+            }));
+        }
+        return results;
+    }
+    /**
+     * Read file content with optional line numbers.
+     *
+     * @param filePath - Path to the file to read
+     * @param offset - Starting line offset (0-indexed)
+     * @param limit - Maximum number of lines to read
+     * @returns Formatted content with line numbers
+     */
+    async read(filePath, offset, limit) {
+        const { backend, relativePath } = this.resolveBackend(filePath);
+        return backend.read(relativePath, offset, limit);
+    }
+    /**
+     * Read raw file content as FileData.
+     *
+     * @param filePath - Path to the file to read
+     * @returns Raw file data with content and timestamps
+     */
+    async readRaw(filePath) {
+        const { backend, relativePath } = this.resolveBackend(filePath);
+        return backend.readRaw(relativePath);
+    }
+    /**
+     * Search for pattern matches using regex across all backends.
+     *
+     * Results are aggregated from all backends. Each backend's grep
+     * is limited to its own path scope.
+     *
+     * @param pattern - Regular expression pattern to search for
+     * @param path - Directory to search in (defaults to root)
+     * @param glob - Glob pattern to filter files
+     * @returns Array of matches from all backends
+     */
+    async grepRaw(pattern, path, glob) {
+        const searchPath = path ?? "/";
+        // Collect results from all relevant backends
+        const allMatches = [];
+        // Check if path targets a specific backend
+        const route = this.findMatchingRoute(searchPath);
+        if (route) {
+            // Single backend search
+            const relativePath = this.toRelativePath(searchPath, route.prefix);
+            const results = await route.backend.grepRaw(pattern, relativePath, glob);
+            const matches = typeof results === "string" ? [] : results;
+            allMatches.push(...matches.map((m) => ({
+                ...m,
+                path: this.toCompositePath(m.path, route.prefix),
+            })));
+        }
+        else {
+            // Search across all backends
+            const searchPromises = [];
+            // Search default backend
+            searchPromises.push(Promise.resolve(this.defaultBackend.grepRaw(pattern, searchPath, glob))
+                .then((results) => (typeof results === "string" ? [] : results))
+                .catch(() => []));
+            // Search each routed backend if the search path is a parent of the route
+            for (const { prefix, backend } of this.routes) {
+                if (this.isParentPath(searchPath, prefix)) {
+                    const relativePath = searchPath === "/" ? "/" : this.toRelativePath(prefix, searchPath);
+                    searchPromises.push(Promise.resolve(backend.grepRaw(pattern, relativePath, glob))
+                        .then((results) => (typeof results === "string" ? [] : results))
+                        .then((matches) => matches.map((m) => ({
+                        ...m,
+                        path: this.toCompositePath(m.path, prefix),
+                    })))
+                        .catch(() => []));
+                }
+            }
+            const allResults = await Promise.all(searchPromises);
+            for (const results of allResults) {
+                allMatches.push(...results);
+            }
+        }
+        return allMatches;
+    }
+    /**
+     * Find files matching a glob pattern across all backends.
+     *
+     * Results are aggregated from all backends that could contain
+     * matching files.
+     *
+     * @param pattern - Glob pattern
+     * @param path - Base directory for the search
+     * @returns Array of matching file info from all backends
+     */
+    async globInfo(pattern, path) {
+        const searchPath = path ?? "/";
+        // Collect results from all relevant backends
+        const allFiles = [];
+        // Check if path targets a specific backend
+        const route = this.findMatchingRoute(searchPath);
+        if (route) {
+            // Single backend search
+            const relativePath = this.toRelativePath(searchPath, route.prefix);
+            const results = await route.backend.globInfo(pattern, relativePath);
+            allFiles.push(...results.map((f) => ({
+                ...f,
+                path: this.toCompositePath(f.path, route.prefix),
+            })));
+        }
+        else {
+            // Search across all backends
+            const searchPromises = [];
+            // Search default backend
+            searchPromises.push(Promise.resolve(this.defaultBackend.globInfo(pattern, searchPath)).catch(() => []));
+            // Search each routed backend if the search path is a parent of the route
+            for (const { prefix, backend } of this.routes) {
+                if (this.isParentPath(searchPath, prefix)) {
+                    searchPromises.push(Promise.resolve(backend.globInfo(pattern, "/"))
+                        .then((files) => files.map((f) => ({
+                        ...f,
+                        path: this.toCompositePath(f.path, prefix),
+                    })))
+                        .catch(() => []));
+                }
+            }
+            const allResults = await Promise.all(searchPromises);
+            for (const results of allResults) {
+                allFiles.push(...results);
+            }
+        }
+        return allFiles;
+    }
+    /**
+     * Create or overwrite a file.
+     *
+     * Routes to the appropriate backend based on path prefix.
+     *
+     * @param filePath - Path for the new file
+     * @param content - Content to write
+     * @returns Result indicating success or failure
+     */
+    async write(filePath, content) {
+        const { backend, relativePath } = this.resolveBackend(filePath);
+        const result = await backend.write(relativePath, content);
+        // Map the path back if needed
+        if (result.path) {
+            const route = this.findMatchingRoute(filePath);
+            if (route) {
+                result.path = this.toCompositePath(result.path, route.prefix);
+            }
+        }
+        return result;
+    }
+    /**
+     * Edit a file by replacing text.
+     *
+     * Routes to the appropriate backend based on path prefix.
+     *
+     * @param filePath - Path to the file to edit
+     * @param oldString - Text to find and replace
+     * @param newString - Replacement text
+     * @param replaceAll - If true, replace all occurrences
+     * @returns Result indicating success or failure
+     */
+    async edit(filePath, oldString, newString, replaceAll) {
+        const { backend, relativePath } = this.resolveBackend(filePath);
+        const result = await backend.edit(relativePath, oldString, newString, replaceAll);
+        // Map the path back if needed
+        if (result.path) {
+            const route = this.findMatchingRoute(filePath);
+            if (route) {
+                result.path = this.toCompositePath(result.path, route.prefix);
+            }
+        }
+        return result;
+    }
+    // ===========================================================================
+    // Public Utility Methods
+    // ===========================================================================
+    /**
+     * Get the backend that handles a specific path.
+     *
+     * Useful for debugging or when you need direct access to a specific backend.
+     *
+     * @param path - Path to check
+     * @returns The backend that handles this path
+     */
+    getBackendForPath(path) {
+        return this.resolveBackend(path).backend;
+    }
+    /**
+     * Get all configured routes.
+     *
+     * @returns Array of route configurations sorted by prefix length (longest first)
+     */
+    getRoutes() {
+        return [...this.routes];
+    }
+    /**
+     * Get the default backend.
+     *
+     * @returns The default backend for unmatched paths
+     */
+    getDefaultBackend() {
+        return this.defaultBackend;
+    }
+    // ===========================================================================
+    // Private Helpers
+    // ===========================================================================
+    /**
+     * Normalize a route prefix.
+     * @internal
+     */
+    normalizePrefix(prefix) {
+        let normalized = prefix.startsWith("/") ? prefix : `/${prefix}`;
+        if (!normalized.endsWith("/")) {
+            normalized += "/";
+        }
+        return normalized;
+    }
+    /**
+     * Normalize a path.
+     * @internal
+     */
+    normalizePath(path) {
+        let normalized = path.startsWith("/") ? path : `/${path}`;
+        // Collapse multiple slashes
+        normalized = normalized.replace(/\/+/g, "/");
+        return normalized;
+    }
+    /**
+     * Find the matching route for a path using longest-prefix matching.
+     * @internal
+     */
+    findMatchingRoute(path) {
+        const normalizedPath = this.normalizePath(path);
+        // Ensure we match with trailing slash for prefix matching
+        const pathWithSlash = normalizedPath.endsWith("/") ? normalizedPath : `${normalizedPath}/`;
+        // Routes are already sorted by length descending
+        for (const route of this.routes) {
+            if (pathWithSlash.startsWith(route.prefix) || normalizedPath === route.prefix.slice(0, -1)) {
+                return route;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Resolve which backend handles a path and return the relative path.
+     * @internal
+     */
+    resolveBackend(path) {
+        const route = this.findMatchingRoute(path);
+        if (route) {
+            return {
+                backend: route.backend,
+                relativePath: this.toRelativePath(path, route.prefix),
+            };
+        }
+        return {
+            backend: this.defaultBackend,
+            relativePath: this.normalizePath(path),
+        };
+    }
+    /**
+     * Convert a composite path to a relative path for the backend.
+     * @internal
+     */
+    toRelativePath(compositePath, prefix) {
+        const normalizedPath = this.normalizePath(compositePath);
+        // If path equals prefix (without trailing slash), return root
+        if (normalizedPath === prefix.slice(0, -1)) {
+            return "/";
+        }
+        // Remove the prefix
+        if (normalizedPath.startsWith(prefix)) {
+            const relative = normalizedPath.slice(prefix.length);
+            return relative.startsWith("/") ? relative : `/${relative}`;
+        }
+        // Path doesn't start with prefix, return as-is
+        return normalizedPath;
+    }
+    /**
+     * Convert a backend-relative path to a composite path.
+     * @internal
+     */
+    toCompositePath(relativePath, prefix) {
+        const normalizedRelative = this.normalizePath(relativePath);
+        // If relative path is root, return prefix without trailing slash
+        if (normalizedRelative === "/") {
+            return prefix.slice(0, -1);
+        }
+        // Combine prefix and relative path
+        const combined = prefix + normalizedRelative.slice(1);
+        return combined;
+    }
+    /**
+     * Check if parentPath is a parent of (or equal to) childPath.
+     * @internal
+     */
+    isParentPath(parentPath, childPath) {
+        const normalizedParent = this.normalizePath(parentPath);
+        const normalizedChild = this.normalizePath(childPath);
+        // Root is parent of everything
+        if (normalizedParent === "/") {
+            return true;
+        }
+        // Check if child starts with parent
+        const parentWithSlash = normalizedParent.endsWith("/")
+            ? normalizedParent
+            : `${normalizedParent}/`;
+        return normalizedChild.startsWith(parentWithSlash) || normalizedChild === normalizedParent;
+    }
+}
+// =============================================================================
+// Factory Function
+// =============================================================================
+/**
+ * Create a CompositeBackend from options.
+ *
+ * @param options - Configuration options
+ * @returns A new CompositeBackend
+ *
+ * @example
+ * ```typescript
+ * const backend = createCompositeBackend({
+ *   defaultBackend: new StateBackend(state),
+ *   routes: {
+ *     '/memories/': persistentBackend,
+ *     '/workspace/': filesystemBackend,
+ *   },
+ * });
+ * ```
+ *
+ * @category Backend
+ */
+export function createCompositeBackend(options) {
+    return new CompositeBackend(options.defaultBackend, options.routes);
+}
+//# sourceMappingURL=composite.js.map