@ash-cloud/ash-ai 0.1.12 → 0.1.13

package/dist/index.d.cts

@@ -1331,8 +1331,21 @@ interface FileSyncEventData {
     operation: FileSyncOperation;
     /** Who initiated this operation */
     source: FileSyncSource;
-    /** Path of the file */
-    filePath: string;
+    /**
+     * Canonical file path - the logical path used as S3 key
+     * Example: "src/Root.tsx"
+     */
+    canonicalPath: string;
+    /**
+     * Base path / target path prefix used in the sandbox
+     * Example: "." (root), ".claude/files" (default), "my-project"
+     */
+    basePath: string;
+    /**
+     * Full computed path in the sandbox
+     * Example: "src/Root.tsx" (if basePath=".") or ".claude/files/src/Root.tsx" (if basePath=".claude/files")
+     */
+    sandboxPath: string;
     /** Size of the file in bytes */
     fileSize?: number;
     /** Whether the operation succeeded */
@@ -4530,14 +4543,31 @@ declare function createMinioFileStore(config: {
 type FileChangeType = 'add' | 'change' | 'unlink' | 'addDir' | 'unlinkDir';
 /**
  * Event emitted when a file changes in the watched directory
+ *
+ * Path terminology:
+ * - relativePath: Path relative to the watch directory (e.g., "src/Root.tsx")
+ * - absolutePath: Full filesystem path (e.g., "/workspace/src/Root.tsx")
+ * - basePath: The watch directory path (e.g., ".", ".claude/files")
  */
 interface FileChangeEvent {
     /** Type of change */
     type: FileChangeType;
-    /** Relative path from the watched directory */
+    /**
+     * Relative path from the watched directory
+     * This is the canonical path for storage purposes
+     * Example: "src/Root.tsx"
+     */
     relativePath: string;
-    /** Absolute path to the file */
+    /**
+     * Absolute filesystem path to the file
+     * Example: "/workspace/src/Root.tsx" or "/vercel/sandbox/.claude/files/src/Root.tsx"
+     */
     absolutePath: string;
+    /**
+     * The base path being watched (the watch directory)
+     * Example: "." (root), ".claude/files" (default)
+     */
+    basePath: string;
     /** Session ID this watch is associated with */
     sessionId: string;
     /** File size (only for add/change events) */
@@ -4969,8 +4999,16 @@ interface FilePushResult {
 interface PushOptions {
     /**
      * Override the sandbox target path for these files.
-     * Default uses sandboxBasePath (.claude/files).
-     * Use '.' to write to sandbox working directory root.
+     * This REPLACES the default sandboxBasePath - it does NOT nest under it.
+     *
+     * Path resolution (for file path 'src/Root.tsx'):
+     * - undefined (default) → .claude/files/src/Root.tsx
+     * - '.'                 → src/Root.tsx (working dir root)
+     * - 'my-project'        → my-project/src/Root.tsx
+     * - '.claude/files'     → .claude/files/src/Root.tsx (same as undefined)
+     *
+     * Note: There is NO double-nesting. targetPath: '.claude/files' does NOT
+     * result in .claude/files/.claude/files/path.
      */
     targetPath?: string;
     /**
@@ -4996,8 +5034,12 @@ interface FilePullResult {
 interface PullOptions {
     /**
      * Override the sandbox source path for reading files.
-     * Default uses sandboxBasePath (.claude/files).
-     * Use '.' to read from sandbox working directory root.
+     * This REPLACES the default sandboxBasePath - it does NOT nest under it.
+     *
+     * Path resolution (for file path 'src/Root.tsx'):
+     * - undefined (default) → reads from .claude/files/src/Root.tsx
+     * - '.'                 → reads from src/Root.tsx (working dir root)
+     * - 'my-project'        → reads from my-project/src/Root.tsx
      *
      * This is useful when watching files edited by the agent,
      * which are at the sandbox root rather than in sandboxBasePath.
@@ -5017,12 +5059,31 @@ interface SyncResult {
 /**
  * Event emitted during file sync operations
  * Operation names are fully explicit about source and destination
+ *
+ * Path terminology:
+ * - canonicalPath: The logical file path (e.g., "src/Root.tsx") - used as S3 key
+ * - basePath: The target prefix in sandbox (e.g., ".", ".claude/files", "my-project")
+ * - sandboxPath: The computed path in sandbox (e.g., "src/Root.tsx" or ".claude/files/src/Root.tsx")
  */
 interface FileSyncEvent {
     operation: 'client_uploaded_to_ash_storage' | 'agent_sandbox_saved_to_ash_storage' | 'ash_storage_synced_to_agent_sandbox' | 'read_from_agent_sandbox' | 'deleted_from_ash_storage' | 'deleted_from_agent_sandbox';
     /** Who initiated this operation */
     source: 'client_api' | 'ash_file_sync';
-    filePath: string;
+    /**
+     * Canonical file path - the logical path used as S3 key
+     * Example: "src/Root.tsx"
+     */
+    canonicalPath: string;
+    /**
+     * Base path / target path prefix used in the sandbox
+     * Example: "." (root), ".claude/files" (default), "my-project"
+     */
+    basePath: string;
+    /**
+     * Full computed path in the sandbox
+     * Example: "src/Root.tsx" (if basePath=".") or ".claude/files/src/Root.tsx" (if basePath=".claude/files")
+     */
+    sandboxPath: string;
     fileSize?: number;
     success: boolean;
     error?: string;
@@ -5197,12 +5258,23 @@ declare class SandboxFileSync {
      * This is called by the cloud layer after creating the sync service
      */
     setSandboxOperations(ops: SandboxFileOperations): void;
+    /**
+     * Get the effective base path for sandbox operations
+     * @param targetPath - Optional override for the base path
+     */
+    private getBasePath;
     /**
      * Get the full sandbox path for a file
      * @param path - The relative file path
      * @param targetPath - Optional override for the base path
      */
     private getSandboxPath;
+    /**
+     * Build all path fields for a FileSyncEvent
+     * @param path - The canonical file path (used as S3 key)
+     * @param targetPath - Optional override for the base path
+     */
+    private buildPathFields;
     /**
      * Push a file: writes to S3, then to sandbox if running
      * @param sessionId - Session ID

package/dist/index.d.ts

@@ -1331,8 +1331,21 @@ interface FileSyncEventData {
     operation: FileSyncOperation;
     /** Who initiated this operation */
     source: FileSyncSource;
-    /** Path of the file */
-    filePath: string;
+    /**
+     * Canonical file path - the logical path used as S3 key
+     * Example: "src/Root.tsx"
+     */
+    canonicalPath: string;
+    /**
+     * Base path / target path prefix used in the sandbox
+     * Example: "." (root), ".claude/files" (default), "my-project"
+     */
+    basePath: string;
+    /**
+     * Full computed path in the sandbox
+     * Example: "src/Root.tsx" (if basePath=".") or ".claude/files/src/Root.tsx" (if basePath=".claude/files")
+     */
+    sandboxPath: string;
     /** Size of the file in bytes */
     fileSize?: number;
     /** Whether the operation succeeded */
@@ -4530,14 +4543,31 @@ declare function createMinioFileStore(config: {
 type FileChangeType = 'add' | 'change' | 'unlink' | 'addDir' | 'unlinkDir';
 /**
  * Event emitted when a file changes in the watched directory
+ *
+ * Path terminology:
+ * - relativePath: Path relative to the watch directory (e.g., "src/Root.tsx")
+ * - absolutePath: Full filesystem path (e.g., "/workspace/src/Root.tsx")
+ * - basePath: The watch directory path (e.g., ".", ".claude/files")
  */
 interface FileChangeEvent {
     /** Type of change */
     type: FileChangeType;
-    /** Relative path from the watched directory */
+    /**
+     * Relative path from the watched directory
+     * This is the canonical path for storage purposes
+     * Example: "src/Root.tsx"
+     */
     relativePath: string;
-    /** Absolute path to the file */
+    /**
+     * Absolute filesystem path to the file
+     * Example: "/workspace/src/Root.tsx" or "/vercel/sandbox/.claude/files/src/Root.tsx"
+     */
     absolutePath: string;
+    /**
+     * The base path being watched (the watch directory)
+     * Example: "." (root), ".claude/files" (default)
+     */
+    basePath: string;
     /** Session ID this watch is associated with */
     sessionId: string;
     /** File size (only for add/change events) */
@@ -4969,8 +4999,16 @@ interface FilePushResult {
 interface PushOptions {
     /**
      * Override the sandbox target path for these files.
-     * Default uses sandboxBasePath (.claude/files).
-     * Use '.' to write to sandbox working directory root.
+     * This REPLACES the default sandboxBasePath - it does NOT nest under it.
+     *
+     * Path resolution (for file path 'src/Root.tsx'):
+     * - undefined (default) → .claude/files/src/Root.tsx
+     * - '.'                 → src/Root.tsx (working dir root)
+     * - 'my-project'        → my-project/src/Root.tsx
+     * - '.claude/files'     → .claude/files/src/Root.tsx (same as undefined)
+     *
+     * Note: There is NO double-nesting. targetPath: '.claude/files' does NOT
+     * result in .claude/files/.claude/files/path.
      */
     targetPath?: string;
     /**
@@ -4996,8 +5034,12 @@ interface FilePullResult {
 interface PullOptions {
     /**
      * Override the sandbox source path for reading files.
-     * Default uses sandboxBasePath (.claude/files).
-     * Use '.' to read from sandbox working directory root.
+     * This REPLACES the default sandboxBasePath - it does NOT nest under it.
+     *
+     * Path resolution (for file path 'src/Root.tsx'):
+     * - undefined (default) → reads from .claude/files/src/Root.tsx
+     * - '.'                 → reads from src/Root.tsx (working dir root)
+     * - 'my-project'        → reads from my-project/src/Root.tsx
      *
      * This is useful when watching files edited by the agent,
      * which are at the sandbox root rather than in sandboxBasePath.
@@ -5017,12 +5059,31 @@ interface SyncResult {
 /**
  * Event emitted during file sync operations
  * Operation names are fully explicit about source and destination
+ *
+ * Path terminology:
+ * - canonicalPath: The logical file path (e.g., "src/Root.tsx") - used as S3 key
+ * - basePath: The target prefix in sandbox (e.g., ".", ".claude/files", "my-project")
+ * - sandboxPath: The computed path in sandbox (e.g., "src/Root.tsx" or ".claude/files/src/Root.tsx")
  */
 interface FileSyncEvent {
     operation: 'client_uploaded_to_ash_storage' | 'agent_sandbox_saved_to_ash_storage' | 'ash_storage_synced_to_agent_sandbox' | 'read_from_agent_sandbox' | 'deleted_from_ash_storage' | 'deleted_from_agent_sandbox';
     /** Who initiated this operation */
     source: 'client_api' | 'ash_file_sync';
-    filePath: string;
+    /**
+     * Canonical file path - the logical path used as S3 key
+     * Example: "src/Root.tsx"
+     */
+    canonicalPath: string;
+    /**
+     * Base path / target path prefix used in the sandbox
+     * Example: "." (root), ".claude/files" (default), "my-project"
+     */
+    basePath: string;
+    /**
+     * Full computed path in the sandbox
+     * Example: "src/Root.tsx" (if basePath=".") or ".claude/files/src/Root.tsx" (if basePath=".claude/files")
+     */
+    sandboxPath: string;
     fileSize?: number;
     success: boolean;
     error?: string;
@@ -5197,12 +5258,23 @@ declare class SandboxFileSync {
      * This is called by the cloud layer after creating the sync service
      */
     setSandboxOperations(ops: SandboxFileOperations): void;
+    /**
+     * Get the effective base path for sandbox operations
+     * @param targetPath - Optional override for the base path
+     */
+    private getBasePath;
     /**
      * Get the full sandbox path for a file
      * @param path - The relative file path
      * @param targetPath - Optional override for the base path
      */
     private getSandboxPath;
+    /**
+     * Build all path fields for a FileSyncEvent
+     * @param path - The canonical file path (used as S3 key)
+     * @param targetPath - Optional override for the base path
+     */
+    private buildPathFields;
     /**
      * Push a file: writes to S3, then to sandbox if running
      * @param sessionId - Session ID

package/dist/index.js

@@ -5993,6 +5993,7 @@ var init_sandbox_file_watcher = __esm({
           type,
           relativePath,
           absolutePath,
+          basePath: this.watchPath,
           sessionId: this.sessionId,
           fileSize,
           timestamp: /* @__PURE__ */ new Date()
@@ -6201,6 +6202,7 @@ var init_sandbox_file_watcher = __esm({
               type: "add",
               relativePath: filePath,
               absolutePath: `${this.basePath}/${filePath}`,
+              basePath: this.basePath,
               sessionId: this.sessionId,
               fileSize: info.size,
               timestamp: /* @__PURE__ */ new Date()
@@ -6213,6 +6215,7 @@ var init_sandbox_file_watcher = __esm({
               type: "unlink",
               relativePath: filePath,
               absolutePath: `${this.basePath}/${filePath}`,
+              basePath: this.basePath,
               sessionId: this.sessionId,
               timestamp: /* @__PURE__ */ new Date()
             });
@@ -6517,7 +6520,7 @@ var init_sandbox_file_sync = __esm({
           }
         };
         const webhookType = payload.event === "file_sync" ? "file_sync" : "file_change";
-        const filePath = payload.fileSyncEvent?.filePath ?? payload.fileChangeEvent?.relativePath;
+        const filePath = payload.fileSyncEvent?.canonicalPath ?? payload.fileChangeEvent?.relativePath;
         const operation = payload.fileSyncEvent?.operation ?? payload.fileChangeEvent?.type;
         if (isAsync) {
           sendWithRetry(0).then(async (result) => {
@@ -6647,7 +6650,9 @@ var init_sandbox_file_sync = __esm({
             const eventData = {
               operation: event.operation,
               source: event.source,
-              filePath: event.filePath,
+              canonicalPath: event.canonicalPath,
+              basePath: event.basePath,
+              sandboxPath: event.sandboxPath,
               fileSize: event.fileSize,
               success: event.success,
               error: event.error,
@@ -6678,6 +6683,13 @@ var init_sandbox_file_sync = __esm({
       setSandboxOperations(ops) {
         this.sandboxOps = ops;
       }
+      /**
+       * Get the effective base path for sandbox operations
+       * @param targetPath - Optional override for the base path
+       */
+      getBasePath(targetPath) {
+        return targetPath ?? this.sandboxBasePath;
+      }
       /**
        * Get the full sandbox path for a file
        * @param path - The relative file path
@@ -6685,12 +6697,30 @@ var init_sandbox_file_sync = __esm({
        */
       getSandboxPath(path15, targetPath) {
         const normalizedPath = path15.replace(/^\/+/, "");
-        const basePath = targetPath ?? this.sandboxBasePath;
+        const basePath = this.getBasePath(targetPath);
         if (basePath === ".") {
           return normalizedPath;
         }
         return `${basePath}/${normalizedPath}`;
       }
+      /**
+       * Build all path fields for a FileSyncEvent
+       * @param path - The canonical file path (used as S3 key)
+       * @param targetPath - Optional override for the base path
+       */
+      buildPathFields(path15, targetPath) {
+        const normalizedPath = path15.replace(/^\/+/, "");
+        const basePath = this.getBasePath(targetPath);
+        const sandboxPath = this.getSandboxPath(path15, targetPath);
+        return {
+          canonicalPath: normalizedPath,
+          // The logical path (S3 key)
+          basePath,
+          // The prefix used in sandbox
+          sandboxPath
+          // Full computed path in sandbox
+        };
+      }
       /**
        * Push a file: writes to S3, then to sandbox if running
        * @param sessionId - Session ID
@@ -6707,13 +6737,14 @@ var init_sandbox_file_sync = __esm({
         };
         const source = options?.source ?? "client_api";
         const uploadToStorageOp = source === "client_api" ? "client_uploaded_to_ash_storage" : "agent_sandbox_saved_to_ash_storage";
+        const pathFields = this.buildPathFields(path15, options?.targetPath);
         try {
           await this.fileStore.writeFile(sessionId, path15, content);
           result.s3Written = true;
           await this.emitFileEvent(sessionId, {
             operation: uploadToStorageOp,
             source,
-            filePath: path15,
+            ...pathFields,
             fileSize: content.length,
             success: true,
             previousContent,
@@ -6726,7 +6757,7 @@ var init_sandbox_file_sync = __esm({
           await this.emitFileEvent(sessionId, {
             operation: uploadToStorageOp,
             source,
-            filePath: path15,
+            ...pathFields,
             fileSize: content.length,
             success: false,
             error: errorMessage
@@ -6735,13 +6766,12 @@ var init_sandbox_file_sync = __esm({
         }
         if (this.sandboxOps?.isSandboxRunning(sessionId)) {
           try {
-            const sandboxPath = this.getSandboxPath(path15, options?.targetPath);
-            const writeResult = await this.sandboxOps.writeFile(sessionId, sandboxPath, content);
+            const writeResult = await this.sandboxOps.writeFile(sessionId, pathFields.sandboxPath, content);
             result.sandboxWritten = writeResult.success;
             await this.emitFileEvent(sessionId, {
               operation: "ash_storage_synced_to_agent_sandbox",
               source,
-              filePath: path15,
+              ...pathFields,
               fileSize: content.length,
               success: writeResult.success,
               error: writeResult.error
@@ -6755,7 +6785,7 @@ var init_sandbox_file_sync = __esm({
             await this.emitFileEvent(sessionId, {
               operation: "ash_storage_synced_to_agent_sandbox",
               source,
-              filePath: path15,
+              ...pathFields,
               fileSize: content.length,
               success: false,
               error: errorMessage
@@ -6798,15 +6828,15 @@ var init_sandbox_file_sync = __esm({
           result.error = "Sandbox is not running";
           return result;
         }
+        const pathFields = this.buildPathFields(path15, options?.targetPath);
         try {
-          const sandboxPath = this.getSandboxPath(path15, options?.targetPath);
-          const readResult = await this.sandboxOps.readFile(sessionId, sandboxPath);
+          const readResult = await this.sandboxOps.readFile(sessionId, pathFields.sandboxPath);
           if (!readResult.success || !readResult.content) {
             result.error = readResult.error ?? "File not found in sandbox";
             await this.emitFileEvent(sessionId, {
               operation: "read_from_agent_sandbox",
               source: "ash_file_sync",
-              filePath: path15,
+              ...pathFields,
               success: false,
               error: result.error
             });
@@ -6816,7 +6846,7 @@ var init_sandbox_file_sync = __esm({
           await this.emitFileEvent(sessionId, {
             operation: "read_from_agent_sandbox",
             source: "ash_file_sync",
-            filePath: path15,
+            ...pathFields,
             fileSize: readResult.content.length,
             success: true,
             newContent: readResult.content
@@ -6827,7 +6857,7 @@ var init_sandbox_file_sync = __esm({
           await this.emitFileEvent(sessionId, {
             operation: "read_from_agent_sandbox",
             source: "ash_file_sync",
-            filePath: path15,
+            ...pathFields,
             success: false,
             error: errorMessage
           });
@@ -6839,7 +6869,7 @@ var init_sandbox_file_sync = __esm({
           await this.emitFileEvent(sessionId, {
             operation: "agent_sandbox_saved_to_ash_storage",
             source: "ash_file_sync",
-            filePath: path15,
+            ...pathFields,
             fileSize: result.content.length,
             success: true,
             newContent: result.content
@@ -6851,7 +6881,7 @@ var init_sandbox_file_sync = __esm({
           await this.emitFileEvent(sessionId, {
             operation: "agent_sandbox_saved_to_ash_storage",
             source: "ash_file_sync",
-            filePath: path15,
+            ...pathFields,
             fileSize: result.content?.length,
             success: false,
             error: errorMessage
@@ -6893,13 +6923,14 @@ var init_sandbox_file_sync = __esm({
        */
       async deleteFile(sessionId, path15) {
         const result = { s3Deleted: false, sandboxDeleted: false };
+        const pathFields = this.buildPathFields(path15);
         try {
           await this.fileStore.deleteFile(sessionId, path15);
           result.s3Deleted = true;
           await this.emitFileEvent(sessionId, {
             operation: "deleted_from_ash_storage",
             source: "ash_file_sync",
-            filePath: path15,
+            ...pathFields,
             success: true
           });
         } catch (error) {
@@ -6908,20 +6939,19 @@ var init_sandbox_file_sync = __esm({
           await this.emitFileEvent(sessionId, {
             operation: "deleted_from_ash_storage",
             source: "ash_file_sync",
-            filePath: path15,
+            ...pathFields,
             success: false,
             error: errorMessage
           });
         }
         if (this.sandboxOps?.isSandboxRunning(sessionId)) {
           try {
-            const sandboxPath = this.getSandboxPath(path15);
-            console.log(`[FILE_SYNC] Would delete ${sandboxPath} from sandbox`);
+            console.log(`[FILE_SYNC] Would delete ${pathFields.sandboxPath} from sandbox`);
             result.sandboxDeleted = true;
             await this.emitFileEvent(sessionId, {
               operation: "deleted_from_agent_sandbox",
               source: "ash_file_sync",
-              filePath: path15,
+              ...pathFields,
               success: true
             });
           } catch (error) {
@@ -6929,7 +6959,7 @@ var init_sandbox_file_sync = __esm({
             await this.emitFileEvent(sessionId, {
               operation: "deleted_from_agent_sandbox",
               source: "ash_file_sync",
-              filePath: path15,
+              ...pathFields,
               success: false,
               error: errorMessage
             });
@@ -6949,6 +6979,7 @@ var init_sandbox_file_sync = __esm({
         }
         const files = await this.fileStore.listFiles(sessionId);
         for (const file of files) {
+          const pathFields = this.buildPathFields(file.path);
           try {
             const content = await this.fileStore.readFile(sessionId, file.path);
             if (!content) {
@@ -6956,20 +6987,19 @@ var init_sandbox_file_sync = __esm({
               await this.emitFileEvent(sessionId, {
                 operation: "ash_storage_synced_to_agent_sandbox",
                 source: "ash_file_sync",
-                filePath: file.path,
+                ...pathFields,
                 success: false,
                 error: "File not found in Ash storage"
               });
               continue;
             }
-            const sandboxPath = this.getSandboxPath(file.path);
-            const writeResult = await this.sandboxOps.writeFile(sessionId, sandboxPath, content);
+            const writeResult = await this.sandboxOps.writeFile(sessionId, pathFields.sandboxPath, content);
             if (writeResult.success) {
               result.fileCount++;
               await this.emitFileEvent(sessionId, {
                 operation: "ash_storage_synced_to_agent_sandbox",
                 source: "ash_file_sync",
-                filePath: file.path,
+                ...pathFields,
                 fileSize: content.length,
                 success: true
               });
@@ -6978,7 +7008,7 @@ var init_sandbox_file_sync = __esm({
               await this.emitFileEvent(sessionId, {
                 operation: "ash_storage_synced_to_agent_sandbox",
                 source: "ash_file_sync",
-                filePath: file.path,
+                ...pathFields,
                 fileSize: content.length,
                 success: false,
                 error: writeResult.error
@@ -6993,7 +7023,7 @@ var init_sandbox_file_sync = __esm({
             await this.emitFileEvent(sessionId, {
               operation: "ash_storage_synced_to_agent_sandbox",
               source: "ash_file_sync",
-              filePath: file.path,
+              ...pathFields,
               success: false,
               error: errorMessage
             });
@@ -7024,24 +7054,25 @@ var init_sandbox_file_sync = __esm({
             return result;
           }
         }
-        for (const filePath of filesToSync) {
+        for (const file of filesToSync) {
+          const pathFields = this.buildPathFields(file);
           try {
-            const pullResult = await this.pullFile(sessionId, filePath);
+            const pullResult = await this.pullFile(sessionId, file);
             if (pullResult.s3Written) {
               result.fileCount++;
             } else if (pullResult.error) {
-              result.errors.push({ path: filePath, error: pullResult.error });
+              result.errors.push({ path: file, error: pullResult.error });
             }
           } catch (error) {
             const errorMessage = extractErrorMessage(error);
             result.errors.push({
-              path: filePath,
+              path: file,
               error: errorMessage
             });
             await this.emitFileEvent(sessionId, {
               operation: "agent_sandbox_saved_to_ash_storage",
               source: "ash_file_sync",
-              filePath,
+              ...pathFields,
               success: false,
               error: errorMessage
             });
@@ -7455,6 +7486,7 @@ WATCHER_EOF`;
                 type: data.type,
                 relativePath: data.path.replace(/^\.\//, ""),
                 absolutePath: data.path,
+                basePath: this.watchPath,
                 sessionId: this.sessionId,
                 timestamp: new Date(data.timestamp)
               });